@blockrun/franklin 3.15.55 → 3.15.57

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

@@ -6,14 +6,23 @@
  * - 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;
     /** User-facing suggestion for how to recover. Appended to error message in UI. */
     suggestion?: string;
+    /**
+     * Upstream-recommended wait time before retrying. Parsed from a
+     * `[retry-after-ms=...]` tag the streaming client appends to the error
+     * message when the response carries a `Retry-After` header (typically
+     * 429 / 503). The agent loop should honor this in place of its
+     * default exponential backoff. Capped at 10 minutes upstream so a
+     * malicious or buggy server can't pin the agent indefinitely.
+     */
+    retryAfterMs?: number;
 }
 export declare function classifyAgentError(message: string): AgentErrorInfo;

package/dist/agent/error-classifier.js

@@ -11,10 +11,42 @@ function includesAny(text, patterns) {
 }
 export function classifyAgentError(message) {
     const err = message.toLowerCase();
+    // Extract Retry-After hint that streaming-client appended (see llm.ts
+    // 429 path). Surfaces on the AgentErrorInfo so the loop can honor the
+    // upstream's recommended wait instead of guessing with exponential
+    // backoff.
+    let retryAfterMs;
+    const retryAfterTag = /\[retry-after-ms=(\d+)\]/i.exec(message);
+    if (retryAfterTag) {
+        const n = parseInt(retryAfterTag[1], 10);
+        if (Number.isFinite(n) && n > 0 && n <= 600_000)
+            retryAfterMs = n;
+    }
+    // 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',
@@ -55,6 +87,7 @@ export function classifyAgentError(message) {
         return {
             category: 'rate_limit', label: 'RateLimit', isTransient: true, maxRetries: 1,
             suggestion: 'Try /model to switch to a different model, or wait a moment and /retry.',
+            retryAfterMs,
         };
     }
     if (includesAny(err, [

package/dist/agent/llm.js

@@ -430,7 +430,25 @@ export class ModelClient {
             }
             if (!response.ok) {
                 const errorBody = await response.text().catch(() => 'unknown error');
-                const message = extractApiErrorMessage(errorBody);
+                let message = extractApiErrorMessage(errorBody);
+                // 429 with Retry-After header: tag the error message so the
+                // classifier can extract and the loop can honor it. Verified
+                // 2026-05-04 in a live session: a 429 fired with the loop's
+                // exponential backoff (~1-2s) but the upstream's actual
+                // Retry-After window was ~30s — the agent retried prematurely
+                // and burned its rate_limit retry budget. Anthropic + most
+                // gateways send Retry-After as either seconds (integer) or an
+                // HTTP-date; we only honor the seconds form (the date form is
+                // rare in practice and harder to validate against clock skew).
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('retry-after');
+                    if (retryAfter) {
+                        const seconds = parseInt(retryAfter, 10);
+                        if (Number.isFinite(seconds) && seconds > 0 && seconds <= 600) {
+                            message = `${message} [retry-after-ms=${seconds * 1000}]`;
+                        }
+                    }
+                }
                 // Runtime tool_choice retry. The static allowlist at line ~35
                 // catches the case where the request goes directly to a model
                 // whose name contains `deepseek-reasoner` / `openai/o1` /

package/dist/agent/loop.js

@@ -1156,8 +1156,17 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         }
                     }
                     recoveryAttempts++;
-                    const backoffMs = getBackoffDelay(recoveryAttempts);
-                    logger.warn(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries}): ${errMsg.slice(0, 100)}`);
+                    // Honor an upstream Retry-After (parsed from the response by
+                    // llm.ts when 429+ Retry-After is present) over our own
+                    // exponential backoff. Verified 2026-05-04: a 429 with
+                    // Retry-After=30s was retried after ~1.5s exponential backoff
+                    // → got 429 again → burned the rate_limit retry budget. Cap at
+                    // 30s so the agent never feels "frozen" — anything longer
+                    // falls back to a different model instead.
+                    const upstreamWaitMs = classified.retryAfterMs;
+                    const honorUpstream = typeof upstreamWaitMs === 'number' && upstreamWaitMs <= 30_000;
+                    const backoffMs = honorUpstream ? upstreamWaitMs : getBackoffDelay(recoveryAttempts);
+                    logger.warn(`[franklin] ${classified.label} error — retrying in ${(backoffMs / 1000).toFixed(1)}s (attempt ${recoveryAttempts}/${effectiveMaxRetries})${honorUpstream ? ' (upstream Retry-After)' : ''}: ${errMsg.slice(0, 100)}`);
                     // Surface the actual error + model so the user can see which model
                     // is failing and what the upstream said. Old "Retrying after Server
                     // error" was uninformative — users couldn't tell whether to wait,
@@ -1172,8 +1181,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.
@@ -1226,7 +1239,18 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     }
                 }
                 // ── Unrecoverable: show error with suggestion from classifier ──
-                const suggestion = classified.suggestion ? `\nTip: ${classified.suggestion}` : '';
+                // For rate_limit specifically, augment the classifier's generic
+                // suggestion with an explicit "all free models exhausted — switch
+                // to a paid model" hint when we got here because pickFreeFallback
+                // returned null. Verified 2026-05-04: the screenshot's session
+                // ended with a bare "[RateLimit] API error: 429" because every
+                // free model had already been ruled out earlier in the turn —
+                // the user had a funded wallet but no signal that paid models
+                // were the way out.
+                let suggestion = classified.suggestion ? `\nTip: ${classified.suggestion}` : '';
+                if (classified.category === 'rate_limit' && turnFailedModels.size > 0) {
+                    suggestion = `\nTip: All free models tried this turn are rate-limited. Switch to a paid model with /model anthropic/claude-sonnet-4.6 (or any other paid model) and retry — your wallet handles it. Or wait ~60s and /retry the same turn.`;
+                }
                 onEvent({
                     kind: 'turn_done',
                     reason: 'error',

package/package.json

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