@blockrun/franklin 3.15.55 → 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

@@ -1172,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.55",
+  "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": {