@blockrun/franklin 3.10.2 → 3.10.5

package/dist/agent/context.js

@@ -165,6 +165,65 @@ Franklin stores wallet keys in ~/.blockrun/. When the user asks about wallet loc
 
 When the user asks about "my wallet" without qualifier, default to Base (it's the primary chain shown at launch). Only mention Solana if the chain file says solana or the user explicitly asks.`;
 }
+function getBlockRunApiSection() {
+    return `# BlockRun Gateway API (the network you live on)
+You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun API", "check all endpoints", or call the gateway directly, use ONLY the paths below. **Never invent, pluralize, or singularize an endpoint** — \`/v1/image/generate\` (singular) is wrong, \`/v1/images/generations\` (plural) is correct. If a path you have in mind isn't in this list, fetch the canonical discovery endpoints before calling it.
+
+**Base URLs**
+- Base chain: \`https://blockrun.ai/api\` (alias: \`https://api.blockrun.ai\`)
+- Solana chain: \`https://sol.blockrun.ai/api\`
+
+**Discovery (always free, GET) — fetch these BEFORE guessing a path**
+- \`GET /openapi.json\` (or \`/.well-known/openapi.json\`) — full OpenAPI 3.1 contract, every route + request schema
+- \`GET /.well-known/x402\` — x402 resource list with prices
+
+**LLM (POST, x402-paid)**
+- \`POST /v1/chat/completions\` — OpenAI-compatible. Body: \`{ model, messages, stream?, tools?, max_tokens?, temperature? }\`. \`model\` MUST come from \`GET /v1/models\` (e.g. \`anthropic/claude-sonnet-4.6\`, \`openai/gpt-5.1\`, \`xai/grok-5\`). Wrong model name → 400 with the valid list in the error body.
+- \`POST /v1/messages\` — Anthropic-compatible. Body: \`{ model, messages, max_tokens, system?, tools? }\`.
+
+**Media (POST, x402-paid; GET to poll async jobs)**
+- \`POST /v1/images/generations\` — text-to-image. Body: \`{ model, prompt, size?, n?, response_format? }\`.
+- \`POST /v1/images/image2image\` — image-to-image. Body: \`{ model, prompt, image, ... }\`.
+- \`GET  /v1/images/generations/{id}\` — fetch a generated image by id.
+- \`POST /v1/videos/generations\` — text/image-to-video. Body: \`{ model, prompt, ... }\`. Returns job id; poll with the GET below.
+- \`GET  /v1/videos/generations/{id}\` — poll video job (settles payment when complete).
+- \`POST /v1/audio/generations\` — music/audio. Body: \`{ model, prompt, ... }\`. Default \`model\`: \`minimax/music-2.5+\`.
+
+**Search (POST, x402-paid)**
+- \`POST /v1/search\` — Exa-backed web search. Body: \`{ query }\` (1–1000 chars).
+- \`/v1/exa/{...path}\` — Exa passthrough (answer / search / contents).
+
+**Markets (GET, free for crypto/FX/commodity; \`stocks\`/\`usstock\` are x402-paid at \$0.001/call)**
+- \`/v1/crypto/list\` · \`/v1/crypto/price/{symbol}\` · \`/v1/crypto/history/{symbol}\`
+- \`/v1/fx/list\` · \`/v1/fx/price/{symbol}\` · \`/v1/fx/history/{symbol}\`
+- \`/v1/commodity/list\` · \`/v1/commodity/price/{symbol}\` · \`/v1/commodity/history/{symbol}\`
+- \`/v1/usstock/list\` · \`/v1/usstock/price/{symbol}\` · \`/v1/usstock/history/{symbol}\`
+- \`/v1/stocks/{market}/list\` · \`/v1/stocks/{market}/price/{symbol}\` · \`/v1/stocks/{market}/history/{symbol}\` (e.g. market = \`hk\`, \`cn\`)
+
+**Wallet & meta (GET, free)**
+- \`GET /v1/balance?address={evmAddress}\` — USDC balance on the configured chain.
+- \`GET /v1/models\` — full model catalog (id, owner, context window, pricing).
+- \`GET /v1/health/overview\` · \`/v1/health/regions\` · \`/v1/health/chain\` · \`/v1/health/models\` — gateway status.
+
+**Sandbox (POST, x402-paid)**
+- \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
+- \`/v1/pm/{...path}\` — prediction-market data passthrough.
+
+**Endpoints that DO NOT exist** (common hallucinations — do NOT call):
+- \`/v1/image/generate\` (singular — use \`/v1/images/generations\`)
+- \`/v1/spending\` (no such route — derive from on-chain history if needed)
+- \`/v1/x/...\` (X/Twitter routes are NOT on the gateway; if a marketing skill exposes \`/v1/x/*\` it's a separate downstream service, not BlockRun gateway)
+
+**Auth pattern (x402)**
+1. POST without a payment header → server returns \`402 Payment Required\` with payment requirements in JSON.
+2. Sign a USDC transfer to the resource address (Base or Solana, per gateway).
+3. Re-POST with header \`X-PAYMENT: <base64-payload>\`.
+4. Server settles on-chain and returns the result.
+
+A bare \`402\` on a POST means the endpoint is healthy and the payment flow is working — that is **not** a bug, do not report it as one. A \`404\` means the path is wrong; fix the path. A \`400\` means the body shape or \`model\` is wrong; the error body lists the valid values.
+
+**Verifying gateway health**: GET \`/v1/health/overview\` (free) is the right probe. Listing endpoints? Fetch \`/openapi.json\` and read the \`paths\` object — that is the source of truth, not your training memory.`;
+}
 function getToolPatternsSection() {
     return `# Tool Selection Patterns
 - **Finding files**: Glob first (by name/pattern), then Grep (by content), then Read (specific file). Don't start with Read unless you know the exact path.
@@ -232,6 +291,7 @@ export function assembleInstructions(workingDir, model) {
         getSocialMarketingSection(),
         getMissingAccessSection(),
         getWalletKnowledgeSection(),
+        getBlockRunApiSection(),
         getToolPatternsSection(),
         getTokenEfficiencySection(),
         getVerificationSection(),

package/dist/agent/error-classifier.js

@@ -44,9 +44,16 @@ export function classifyAgentError(message) {
         '429',
         'rate limit',
         'too many requests',
+        'too many tokens', // Anthropic per-day TPM cap leak via gateway
+        'tokens per day',
+        'please wait before trying',
+        'quota exceeded',
     ])) {
+        // 1 retry is plenty: a per-second rate limit clears in seconds (one
+        // backoff covers it), but a per-day TPM quota won't clear in this
+        // session at all — caller falls back to a different provider after.
         return {
-            category: 'rate_limit', label: 'RateLimit', isTransient: true,
+            category: 'rate_limit', label: 'RateLimit', isTransient: true, maxRetries: 1,
             suggestion: 'Try /model to switch to a different model, or wait a moment and /retry.',
         };
     }

package/dist/agent/loop.d.ts

@@ -2,7 +2,24 @@
  * Franklin Agent Loop
  * The core reasoning-action cycle: prompt → model → extract capabilities → execute → repeat.
  */
-import type { AgentConfig, Dialogue, StreamEvent } from './types.js';
+import type { AgentConfig, ContentPart, Dialogue, StreamEvent } from './types.js';
+/**
+ * Detect when the gateway leaked an upstream rate-limit / quota error as a
+ * 200-OK text content block instead of a real HTTP error. The Anthropic
+ * provider in particular surfaces per-day TPM exhaustion as a bracketed
+ * "[Error: Too many tokens per day, please wait before trying again.]"
+ * message glued into the assistant text channel, which then poisons grounding
+ * checks and gets persisted to session history as if it were a real reply.
+ *
+ * Treat any assistant turn whose entire text payload is a single bracketed
+ * `[Error: ...]` line — and contains no tool_use / thinking blocks — as a
+ * masquerading transport error. The caller throws to let the existing
+ * classifier + retry path take over.
+ */
+export declare function looksLikeGatewayErrorAsText(parts: ContentPart[]): {
+    match: boolean;
+    message: string;
+};
 /**
  * Identify models known to hallucinate tool calls (invented names, literal
  * `[TOOLCALL]` / `<tool_call>` text in answers) — they need the explicit

package/dist/agent/loop.js

@@ -206,6 +206,42 @@ function stripMediaFromHistory(history) {
     });
     return { history: stripped ? result : history, stripped };
 }
+/**
+ * Detect when the gateway leaked an upstream rate-limit / quota error as a
+ * 200-OK text content block instead of a real HTTP error. The Anthropic
+ * provider in particular surfaces per-day TPM exhaustion as a bracketed
+ * "[Error: Too many tokens per day, please wait before trying again.]"
+ * message glued into the assistant text channel, which then poisons grounding
+ * checks and gets persisted to session history as if it were a real reply.
+ *
+ * Treat any assistant turn whose entire text payload is a single bracketed
+ * `[Error: ...]` line — and contains no tool_use / thinking blocks — as a
+ * masquerading transport error. The caller throws to let the existing
+ * classifier + retry path take over.
+ */
+export function looksLikeGatewayErrorAsText(parts) {
+    if (parts.length === 0)
+        return { match: false, message: '' };
+    // Reject if any non-text content (real tool calls, real thinking) was emitted.
+    const textParts = [];
+    for (const p of parts) {
+        if (p.type === 'tool_use')
+            return { match: false, message: '' };
+        if (p.type === 'text' && typeof p.text === 'string') {
+            textParts.push(p.text);
+        }
+    }
+    const joined = textParts.join('').trim();
+    if (!joined)
+        return { match: false, message: '' };
+    // Pattern: `[Error: ...]` taking up the entire text payload, modulo
+    // surrounding whitespace. Allow the bracket to be the whole message OR
+    // the message to start with it (some gateways append a stray newline).
+    const m = /^\[Error:\s*([^\]]+?)\]\s*$/.exec(joined);
+    if (!m)
+        return { match: false, message: '' };
+    return { match: true, message: m[1].trim() };
+}
 /**
  * Calculate backoff delay with jitter to avoid thundering herd.
  * Base: exponential (2^attempt * 1000ms), jitter: ±25%.
@@ -1024,6 +1060,33 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         continue; // Retry with next model
                     }
                 }
+                // ── Rate-limit / quota: auto-fallback to a different provider ──
+                // Per-day TPM caps (Anthropic) won't clear in this session; per-second
+                // limits already had their backoff retry above and still failed. In
+                // both cases, the productive next move is to run the same turn on a
+                // model from a different provider rather than thrash on the failing
+                // one. Mirror the payment fallback shape: mark the model as failed
+                // for this turn and pick the next free model that hasn't failed yet.
+                if (classified.category === 'rate_limit') {
+                    turnFailedModels.add(config.model);
+                    if (lastRoutedCategory) {
+                        recordOutcome(lastRoutedCategory, config.model, 'rate_limit');
+                    }
+                    const FREE_MODELS = ['nvidia/qwen3-coder-480b', 'nvidia/llama-4-maverick', 'nvidia/glm-4.7'];
+                    const nextFree = FREE_MODELS.find(m => !turnFailedModels.has(m));
+                    if (nextFree) {
+                        const oldModel = config.model;
+                        config.model = nextFree;
+                        config.onModelChange?.(nextFree, 'system');
+                        // Reset retry counter — the new model gets its own retry budget.
+                        recoveryAttempts = 0;
+                        onEvent({
+                            kind: 'text_delta',
+                            text: `\n*${oldModel} rate-limited — switching to ${nextFree}*\n`,
+                        });
+                        continue;
+                    }
+                }
                 // ── Unrecoverable: show error with suggestion from classifier ──
                 const suggestion = classified.suggestion ? `\nTip: ${classified.suggestion}` : '';
                 onEvent({
@@ -1165,6 +1228,20 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 lastSessionActivity = Date.now();
                 continue; // Retry with higher limit
             }
+            // ── Gateway error masquerading as text (BlockRun → Anthropic TPM) ──
+            // Some upstreams swallow rate-limit / quota errors and emit them as a
+            // single bracketed text block on a 200 OK. Persisting that as a real
+            // assistant reply poisons history (the next turn sees an "answer" that
+            // is actually a transport error) and triggers grounding-check retries
+            // that hit the same wall. Detect, throw into the classifier, and let
+            // the existing recovery flow handle it.
+            const gatewayErr = looksLikeGatewayErrorAsText(responseParts);
+            if (gatewayErr.match) {
+                if (config.debug) {
+                    console.error(`[franklin] Gateway returned an error text in lieu of an answer (${resolvedModel}): ${gatewayErr.message}`);
+                }
+                throw new Error(gatewayErr.message);
+            }
             // Reset recovery counter on successful completion
             recoveryAttempts = 0;
             // Extract tool invocations (text/thinking already streamed in real-time)

package/dist/router/local-elo.d.ts

@@ -5,7 +5,7 @@
  * Storage: ~/.blockrun/router-history.jsonl (append-only, capped 2000 records)
  * Never uploaded — purely local personalization.
  */
-export type Outcome = 'continued' | 'switched' | 'retried' | 'error' | 'max_turns' | 'payment';
+export type Outcome = 'continued' | 'switched' | 'retried' | 'error' | 'max_turns' | 'payment' | 'rate_limit';
 /**
  * Record a model outcome for local learning.
  */

package/dist/router/local-elo.js

@@ -92,6 +92,13 @@ export function computeLocalElo() {
                     case 'payment':
                         delta = -K_FACTOR * 1.5;
                         break;
+                    // Rate-limited: provider isn't broken, just exhausted right now.
+                    // Penalize less than payment (which won't clear without action) but
+                    // more than a generic error so the router avoids the same provider
+                    // for the rest of the session.
+                    case 'rate_limit':
+                        delta = -K_FACTOR * 1.2;
+                        break;
                     case 'max_turns':
                         delta = -K_FACTOR * 0.3;
                         break;

package/dist/ui/app.js

@@ -15,6 +15,25 @@ import { estimateCost } from '../pricing.js';
 import { formatTokens, shortModelName } from '../stats/format.js';
 import { mouse, forceDisableMouseTracking } from './mouse.js';
 // ─── Full-width input box ──────────────────────────────────────────────────
+const DISABLE_AUTO_WRAP = '\x1b[?7l';
+const ENABLE_AUTO_WRAP = '\x1b[?7h';
+function disableTerminalAutoWrap() {
+    if (!process.stdout.isTTY)
+        return undefined;
+    let restored = false;
+    const restore = () => {
+        if (restored || !process.stdout.writable)
+            return;
+        restored = true;
+        process.stdout.write(ENABLE_AUTO_WRAP);
+    };
+    process.stdout.write(DISABLE_AUTO_WRAP);
+    process.once('exit', restore);
+    return () => {
+        process.off('exit', restore);
+        restore();
+    };
+}
 // Subscribe to terminal resize so React re-renders with fresh dimensions.
 // Without this, useStdout() returns a stable ref and children that read
 // stdout.columns on each render still need React to re-execute them — which
@@ -775,6 +794,7 @@ export function launchInkUI(opts) {
     let pendingInput = null; // Queue for inputs that arrive before waitForInput
     let exiting = false;
     let abortCallback = null;
+    const restoreTerminalAutoWrap = disableTerminalAutoWrap();
     const instance = render(_jsx(RunCodeApp, { initialModel: opts.model, workDir: opts.workDir, walletAddress: opts.walletAddress || 'not set — run: franklin setup', walletBalance: opts.walletBalance || 'unknown', chain: opts.chain || 'base', startWithPicker: opts.showPicker, onSubmit: (value) => {
             if (resolveInput) {
                 resolveInput(value);
@@ -820,7 +840,11 @@ export function launchInkUI(opts) {
             return new Promise((resolve) => { resolveInput = resolve; });
         },
         onAbort: (cb) => { abortCallback = cb; },
-        cleanup: () => { mouse.disable(); instance.unmount(); },
+        cleanup: () => {
+            mouse.disable();
+            instance.unmount();
+            restoreTerminalAutoWrap?.();
+        },
         requestPermission: (toolName, description) => {
             const ui = globalThis.__franklin_ui;
             return ui?.requestPermission(toolName, description) ?? Promise.resolve('no');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.10.2",
+  "version": "3.10.5",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {
@@ -66,7 +66,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@blockrun/llm": "^1.4.2",
+    "@blockrun/llm": "^1.13.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",