@blockrun/franklin 3.15.22 → 3.15.24

package/dist/agent/loop.js

@@ -606,6 +606,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         const turnToolCounts = new Map(); // Per-tool-name counts this turn
         const readFileCache = new Set(); // Files already read (dedup)
         const MAX_TOOL_CALLS_PER_TURN = 25; // Hard cap per user turn
+        // Hard break threshold for runaways. The cap above is soft — we
+        // inject a "limit reached" tool_result once and let the model
+        // close out. If it ignores that signal and keeps calling tools,
+        // we force end the turn to prevent unbounded billing. Verified
+        // on a real user log: one turn went 25 → 100 tool calls before
+        // the loop ended via maxTurns (much later, much more expensive).
+        const HARD_TOOL_CAP = MAX_TOOL_CALLS_PER_TURN * 2;
+        let toolCapWarned = false; // Log + inject only once per turn
         const SAME_TOOL_WARN_THRESHOLD = 3; // Warn after N calls to same tool (lowered from 5 — search loops were wasting turns)
         // ── No-progress guardrail: kill infinite tiny-response loops ──
         let consecutiveTinyResponses = 0; // Count of consecutive calls with <10 output tokens
@@ -1527,8 +1535,10 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     });
                 }
             }
-            // Hard cap: stop the turn if too many tool calls
-            if (turnToolCalls >= MAX_TOOL_CALLS_PER_TURN) {
+            // Hard cap: nudge the model to stop. Inject once per turn —
+            // re-injecting on every iteration past the cap is just noise
+            // and clutters the model's context with repeated stop signals.
+            if (turnToolCalls >= MAX_TOOL_CALLS_PER_TURN && !toolCapWarned) {
                 outcomeContent.push({
                     type: 'tool_result',
                     tool_use_id: 'guardrail-cap',
@@ -1569,11 +1579,22 @@ 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) {
-                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.
+            // Cap signaling: warn once per turn (was firing every iteration
+            // past the cap — verified on a real user log, one turn produced
+            // 76 sequential warnings 25→100). Hard break at 2× cap stops a
+            // runaway model that ignores the soft stop signal above.
+            if (turnToolCalls >= MAX_TOOL_CALLS_PER_TURN && !toolCapWarned) {
+                toolCapWarned = true;
+                logger.warn(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn (soft cap ${MAX_TOOL_CALLS_PER_TURN}, hard cap ${HARD_TOOL_CAP})`);
+            }
+            if (turnToolCalls >= HARD_TOOL_CAP) {
+                logger.error(`[franklin] Hard tool cap exceeded (${turnToolCalls}) — ending turn to prevent runaway`);
+                onEvent({
+                    kind: 'text_delta',
+                    text: `\n\n⚠️ Tool call limit exceeded (${turnToolCalls}/${HARD_TOOL_CAP}). Ending turn to prevent runaway loop. Try rephrasing or use \`/model\` to switch.\n`,
+                });
+                onEvent({ kind: 'turn_done', reason: 'cap_exceeded' });
+                break;
             }
         }
         if (loopCount >= maxTurns) {

package/dist/agent/types.d.ts

@@ -125,7 +125,7 @@ export interface StreamCapabilityDone {
 }
 export interface StreamTurnDone {
     kind: 'turn_done';
-    reason: 'completed' | 'max_turns' | 'aborted' | 'error' | 'budget' | 'no_progress';
+    reason: 'completed' | 'max_turns' | 'aborted' | 'error' | 'budget' | 'no_progress' | 'cap_exceeded';
     error?: string;
 }
 export interface StreamUsageInfo {

package/dist/mcp/client.js

@@ -5,6 +5,7 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { logger } from '../logger.js';
 // ─── Connection Management ────────────────────────────────────────────────
 const connections = new Map();
 /**
@@ -168,13 +169,9 @@ export async function connectMcpServers(config, debug) {
         if (serverConfig.disabled)
             continue;
         try {
-            if (debug) {
-                console.error(`[franklin] Connecting to MCP server: ${name}...`);
-            }
+            logger.debug(`[franklin] Connecting to MCP server: ${name}...`);
             if (serverConfig.transport !== 'stdio') {
-                if (debug) {
-                    console.error(`[franklin] MCP HTTP transport not yet supported for ${name}`);
-                }
+                logger.debug(`[franklin] MCP HTTP transport not yet supported for ${name}`);
                 continue;
             }
             // Timeout: don't let a slow server block startup
@@ -182,14 +179,18 @@ export async function connectMcpServers(config, debug) {
             const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('connection timeout (5s)')), MCP_CONNECT_TIMEOUT));
             const connected = await Promise.race([connectPromise, timeoutPromise]);
             allTools.push(...connected.tools);
-            if (debug) {
-                console.error(`[franklin] MCP ${name}: ${connected.tools.length} tools discovered`);
-            }
+            logger.info(`[franklin] MCP ${name}: ${connected.tools.length} tools discovered`);
         }
         catch (err) {
             // Graceful degradation — one-line warning, continue without this server.
-            // Always visible (not debug-only) so the user knows why tools are missing.
+            // Always written to franklin-debug.log so the user can post-mortem
+            // why tools went missing; ALSO printed to stderr at session boot
+            // so the user sees it in real time before the agent eats the
+            // terminal. Two separate writes (logger + stderr) is fine here —
+            // the user-visible "tool missing" notice has different timing
+            // requirements than the persistent log entry.
             const shortMsg = err.message?.split('\n')[0]?.slice(0, 100) || 'unknown error';
+            logger.warn(`[franklin] MCP ${name}: ${shortMsg}`);
             console.error(`  ${name}: ${shortMsg} ${debug ? '' : '(--debug for details)'}`);
         }
     }

package/dist/proxy/server.js

@@ -16,6 +16,7 @@ const X_FRANKLIN_VERSION = VERSION;
 // pattern!), and timestamp format — bug fixes never propagated. They
 // were the last holdouts after the agent loop was migrated.
 import { logger, setDebugMode } from '../logger.js';
+import { isTestFixtureModel } from '../stats/test-fixture.js';
 const DEFAULT_MAX_TOKENS = 4096;
 // 180s budget for *time-to-headers* — reasoning-class models (zai/glm-*,
 // nemotron *-reasoning, deepseek-r*, gpt-5-codex, anthropic extended-thinking)
@@ -439,6 +440,11 @@ export function createProxy(options) {
                         solanaWallet,
                         timeoutMs: requestTimeoutMs,
                     }, (failedModel, status, nextModel) => {
+                        // Skip test-fixture model names (slow/, mock/, test/, local/test*)
+                        // — these come from in-process proxy tests with mock servers and
+                        // would otherwise pollute the user's real franklin-debug.log.
+                        if (isTestFixtureModel(failedModel) || isTestFixtureModel(nextModel))
+                            return;
                         logger.warn(`[franklin] ⚠️  ${failedModel} returned ${status}, falling back to ${nextModel}`);
                     });
                     response = result.response;
@@ -446,7 +452,7 @@ export function createProxy(options) {
                     // Use the body with the correct fallback model for payment
                     body = result.bodyUsed;
                     usedFallback = result.fallbackUsed;
-                    if (usedFallback) {
+                    if (usedFallback && !isTestFixtureModel(finalModel)) {
                         logger.info(`[franklin] ↺ Fallback successful: using ${finalModel}`);
                     }
                 }
@@ -678,7 +684,9 @@ async function fetchWithPaymentFallback(url, init, originalBody, config, payment
             if (nextModel && onFallback) {
                 onFallback(model, 0, nextModel);
             }
-            logger.warn(`[franklin] [fallback] ${model} request error: ${err instanceof Error ? err.message : String(err)}`);
+            if (!isTestFixtureModel(model)) {
+                logger.warn(`[franklin] [fallback] ${model} request error: ${err instanceof Error ? err.message : String(err)}`);
+            }
             if (i < config.chain.length - 1) {
                 await sleep(config.retryDelayMs);
             }

package/dist/stats/test-fixture.js

@@ -17,12 +17,26 @@
  * `local/lmstudio`, etc.) are intentionally NOT filtered — only the
  * `local/test` prefix.
  */
+// Prefixes test files use to mark "this isn't a real model name". The
+// list grew by inspection of real franklin-debug.log pollution after
+// 3.15.16 — each new convention surfaced as a writes-to-user-home leak:
+//   `local/test*`  — agent loop in-process tests (test/local.mjs:567 etc.)
+//   `slow/`        — proxy timeout test (test/local.mjs:380)
+//   `mock/`        — generic mock-server fixtures (defensive)
+//   `test/`        — e.g. `test/model` used in some test paths
 const TEST_FIXTURE_PREFIXES = [
     'local/test',
+    'slow/',
+    'mock/',
+    'test/',
 ];
+// Exact-match fixtures (model is literally "test" without a slash).
+const TEST_FIXTURE_EXACT = new Set(['test']);
 export function isTestFixtureModel(model) {
     if (!model)
         return false;
+    if (TEST_FIXTURE_EXACT.has(model))
+        return true;
     for (const prefix of TEST_FIXTURE_PREFIXES) {
         if (model.startsWith(prefix))
             return true;

package/dist/tools/defillama.js

@@ -17,6 +17,7 @@
  */
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
 const TIMEOUT_MS = 30_000;
 // ─── Shared GET-with-x402 flow ────────────────────────────────────────────
 async function getWithPayment(path, ctx) {
@@ -90,7 +91,7 @@ async function signPayment(response, chain, endpoint) {
         return { 'PAYMENT-SIGNATURE': payload };
     }
     catch (err) {
-        console.error(`[franklin] DefiLlama payment error: ${err.message}`);
+        logger.warn(`[franklin] DefiLlama payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/exa.js

@@ -19,6 +19,7 @@
  */
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
 const GEN_TIMEOUT_MS = 30_000;
 // ─── Shared payment flow ─────────────────────────────────────────────
 async function postWithPayment(path, body, ctx) {
@@ -95,7 +96,7 @@ async function signPayment(response, chain, endpoint) {
         return { 'PAYMENT-SIGNATURE': payload };
     }
     catch (err) {
-        console.error(`[franklin] Exa payment error: ${err.message}`);
+        logger.warn(`[franklin] Exa payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/imagegen.js

@@ -11,6 +11,7 @@ import { ModelClient } from '../agent/llm.js';
 import { analyzeMediaRequest, renderProposalForAskUser } from '../agent/media-router.js';
 import { recordUsage } from '../stats/tracker.js';
 import { findModel, estimateCostUsd } from '../gateway-models.js';
+import { logger } from '../logger.js';
 /**
  * Models that accept a reference image via /v1/images/image2image. Currently
  * limited to OpenAI's edit endpoint — Gemini Nano Banana Pro and Grok Imagine
@@ -391,7 +392,7 @@ async function signPayment(response, chain, endpoint) {
         }
     }
     catch (err) {
-        console.error(`[franklin] Image payment error: ${err.message}`);
+        logger.warn(`[franklin] Image payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/modal.js

@@ -29,6 +29,7 @@ import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, creat
 import { loadChain, API_URLS, VERSION } from '../config.js';
 import { walletReservation } from '../wallet/reservation.js';
 import { recordUsage } from '../stats/tracker.js';
+import { logger } from '../logger.js';
 // ─── Pricing table (probed from /.well-known/x402 + 402 responses) ─────────
 const CREATE_PRICE_USD = {
     cpu: 0.01,
@@ -95,7 +96,7 @@ async function signPayment(response, chain, endpoint, resourceDescription) {
         }
     }
     catch (err) {
-        console.error(`[franklin] Modal payment error: ${err.message}`);
+        logger.warn(`[franklin] Modal payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/musicgen.js

@@ -17,6 +17,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
 const DEFAULT_MODEL = 'minimax/music-2.5+';
 const PRICE_USD = 0.1575;
 // MiniMax generation is 1-3 minutes + small buffer for payment + download.
@@ -199,7 +200,7 @@ async function signPayment(response, chain, endpoint) {
         return { 'PAYMENT-SIGNATURE': payload };
     }
     catch (err) {
-        console.error(`[franklin] Music payment error: ${err.message}`);
+        logger.warn(`[franklin] Music payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/videogen.js

@@ -22,6 +22,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
 import { ModelClient } from '../agent/llm.js';
 import { analyzeMediaRequest, renderProposalForAskUser } from '../agent/media-router.js';
 import { recordUsage } from '../stats/tracker.js';
@@ -385,7 +386,7 @@ async function signPayment(response, chain, endpoint) {
         return { 'PAYMENT-SIGNATURE': payload };
     }
     catch (err) {
-        console.error(`[franklin] Video payment error: ${err.message}`);
+        logger.warn(`[franklin] Video payment error: ${err.message}`);
         return null;
     }
 }

package/dist/tools/zerox-gasless.js

@@ -24,6 +24,7 @@ import { createWalletClient, http, publicActions } from 'viem';
 import { getOrCreateWallet } from '@blockrun/llm';
 import { loadConfig } from '../commands/config.js';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
 // ─── Constants ────────────────────────────────────────────────────────────
 const ZEROX_GATEWAY_PATH = '/v1/zerox/gasless';
 const QUOTE_TIMEOUT_MS = 30_000;
@@ -235,7 +236,7 @@ async function pollUntilDone(tradeHash, ctx) {
         }
         catch (err) {
             // Surface a transient failure but keep polling — relayer might be backlogged.
-            console.error(`[franklin] gasless status poll error: ${err.message}`);
+            logger.warn(`[franklin] gasless status poll error: ${err.message}`);
         }
         if (last.status === 'confirmed' ||
             last.status === 'succeeded' ||

package/package.json

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