@blockrun/franklin 3.15.54 → 3.15.56

package/dist/agent/error-classifier.d.ts

@@ -6,10 +6,10 @@
  * - Auth errors (401) get special handling (token refresh, not retry)
  * - EPIPE/connection reset handled as network errors (retryable)
  */
-export type AgentErrorCategory = 'rate_limit' | 'payment' | 'network' | 'timeout' | 'context_limit' | 'overloaded' | 'server' | 'auth' | 'schema' | 'unknown';
+export type AgentErrorCategory = 'rate_limit' | 'payment' | 'payment_rejected' | 'network' | 'timeout' | 'context_limit' | 'overloaded' | 'server' | 'auth' | 'schema' | 'unknown';
 export interface AgentErrorInfo {
     category: AgentErrorCategory;
-    label: 'RateLimit' | 'Payment' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Schema' | 'Unknown';
+    label: 'RateLimit' | 'Payment' | 'PaymentRejected' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Schema' | 'Unknown';
     isTransient: boolean;
     /** Max retries for this error type (overrides default). undefined = use default. */
     maxRetries?: number;

package/dist/agent/error-classifier.js

@@ -11,10 +11,31 @@ function includesAny(text, patterns) {
 }
 export function classifyAgentError(message) {
     const err = message.toLowerCase();
+    // payment_rejected — the gateway received a SIGNED payment header and
+    // rejected it during verification (signature mismatch, replay-nonce
+    // reuse, clock skew, wrong-chain wallet). Different remedy from
+    // payment_required: re-presenting the same signature won't help.
+    // Verified 2026-05-04 in a live session: ExaSearch returned
+    // `Exa /v1/exa/search failed (402): {"error":"Payment verification failed",...}`.
+    // Classify BEFORE the generic 'payment' branch below since the body
+    // contains both 'payment' and 'verification failed'.
+    if (includesAny(err, [
+        'verification failed',
+        'payment verification',
+        'signature mismatch',
+        'invalid payment signature',
+        'invalid x-payment',
+        'nonce reuse',
+        'replay protection',
+    ])) {
+        return {
+            category: 'payment_rejected', label: 'PaymentRejected', isTransient: false, maxRetries: 0,
+            suggestion: 'The gateway rejected your signed payment. Run `franklin balance` to confirm funds + chain. Common causes: clock skew (resync system clock), wrong chain selected (use `/chain` to switch), or stale nonce (the same retry will fail). Switch to a free model with `/model free` to keep working.',
+        };
+    }
     if (includesAny(err, [
         'insufficient',
         'payment',
-        'verification failed',
         'balance',
         '402',
         'free tier',

package/dist/agent/loop.js

@@ -288,6 +288,19 @@ function getBackoffDelay(attempt, maxDelayMs = 32_000) {
     const jitter = base * 0.25 * (Math.random() * 2 - 1); // ±25%
     return Math.max(500, Math.round(base + jitter));
 }
+/**
+ * Format the user-facing "switching model" line. Includes the resolved
+ * concrete model in parentheses when the user-facing alias (e.g.
+ * `blockrun/auto`) differs from what was actually being called (e.g.
+ * `anthropic/claude-sonnet-4.6`). Verified 2026-05-04 in a live session:
+ * a payment fail surfaced as `*blockrun/auto failed — switching to
+ * nvidia/qwen3-coder-480b*` with no hint of which concrete model
+ * actually failed, and no hint of why. The reason label closes that gap.
+ */
+function formatModelSwitch(alias, resolved, reason, newModel) {
+    const oldDisplay = alias === resolved ? alias : `${alias} (${resolved})`;
+    return `${oldDisplay} ${reason} — switching to ${newModel}`;
+}
 /**
  * Identify models known to hallucinate tool calls (invented names, literal
  * `[TOOLCALL]` / `<tool_call>` text in answers) — they need the explicit
@@ -1013,8 +1026,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const oldModel = config.model;
                         config.model = nextModel;
                         config.onModelChange?.(nextModel, 'system');
-                        logger.warn(`[franklin] ${oldModel} returned empty — switching to ${nextModel}`);
-                        onEvent({ kind: 'text_delta', text: `\n*${oldModel} returned empty — switching to ${nextModel}*\n` });
+                        const switchLine = formatModelSwitch(oldModel, resolvedModel, 'returned empty', nextModel);
+                        logger.warn(`[franklin] ${switchLine}`);
+                        onEvent({ kind: 'text_delta', text: `\n*${switchLine}*\n` });
                         continue;
                     }
                     // No fallback available OR already tried 2 models — give up, tell the user.
@@ -1158,8 +1172,12 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 }
                 // ── Payment failure: auto-fallback to free models ──
                 // Track payment-failed models for the entire session — unlike transient errors,
-                // 402s will keep failing until the user adds funds.
-                if (classified.category === 'payment') {
+                // 402s will keep failing until the user adds funds. Also handles
+                // payment_rejected (signature verified-and-rejected by gateway):
+                // same fallback path, but the suggestion text in classifier guides
+                // the user toward clock-skew / chain-mismatch fixes rather than
+                // "add funds."
+                if (classified.category === 'payment' || classified.category === 'payment_rejected') {
                     turnFailedModels.add(config.model);
                     paymentFailedModels.set(config.model, Date.now());
                     // Bound the Map so long sessions don't leak. LRU-evict oldest by timestamp.
@@ -1177,7 +1195,11 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         const oldModel = config.model;
                         config.model = nextFree;
                         config.onModelChange?.(nextFree, 'system');
-                        onEvent({ kind: 'text_delta', text: `\n*${oldModel} failed — switching to ${nextFree}*\n` });
+                        const reason = `failed [${classified.label}]`;
+                        onEvent({
+                            kind: 'text_delta',
+                            text: `\n*${formatModelSwitch(oldModel, resolvedModel, reason, nextFree)}*\n`,
+                        });
                         continue; // Retry with next model
                     }
                 }
@@ -1202,7 +1224,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         recoveryAttempts = 0;
                         onEvent({
                             kind: 'text_delta',
-                            text: `\n*${oldModel} rate-limited — switching to ${nextFree}*\n`,
+                            text: `\n*${formatModelSwitch(oldModel, resolvedModel, 'rate-limited', nextFree)}*\n`,
                         });
                         continue;
                     }

package/package.json

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