@blockrun/franklin 3.15.7 → 3.15.9

package/dist/agent/error-classifier.js

@@ -111,6 +111,28 @@ export function classifyAgentError(message) {
             suggestion: 'The model is overloaded. Try /model to switch, or wait and /retry.',
         };
     }
+    // Reasoning / thinking-mode format errors — NOT transient.
+    // DeepSeek V4 family and similar thinking-enabled models reject requests
+    // when the message history's reasoning_content fields don't match the
+    // upstream's expected shape (typically: tool-call assistant messages must
+    // carry reasoning_content; non-tool-call ones must not, or vice versa).
+    // The fix is to drop the polluting history, not to swap models — every
+    // thinking-enabled model has the same constraint just with different
+    // specifics. /clear forces a fresh context that won't have the bad shape.
+    // Classified BEFORE the generic schema branch below so we surface the
+    // right suggestion.
+    if (includesAny(err, [
+        'reasoning_content',
+        'reasoning content',
+        'thinking mode must',
+        'message format incompatible',
+        'reasoning_format_error',
+    ])) {
+        return {
+            category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+            suggestion: 'Thinking-mode history is incompatible with this model. Use /clear to reset and retry, or /model to switch to a non-thinking model.',
+        };
+    }
     // Schema / tool-definition errors — NOT transient, retrying won't help.
     // These can be wrapped in 5xx responses (e.g. '503: 400 Invalid schema'),
     // so classify them BEFORE the generic server-error branch below.

package/dist/agent/evaluator.js

@@ -65,9 +65,36 @@ Flag as tool-use refusal:
 
 VERDICT: GROUNDED | PARTIAL | UNGROUNDED
 
-If not GROUNDED, list each issue on its own line starting with "- " and the tool that should have been called, like:
-- Claim: "<the ungrounded part, quoted briefly>" → missing tool: <TradingMarket | ExaAnswer | ExaSearch | WebSearch | ...>
-- Refusal: "<the refusal phrase, quoted briefly>" → should have called: <tool name>
+If not GROUNDED, list each issue on its own line starting with "- " and the tool that should have been called.
+
+## Picking the right tool — strict domain rules
+
+**Default for any factual claim:** WebSearch or ExaSearch. These are the
+right answer for the OVERWHELMING majority of "the model said a number it
+didn't look up" cases — current events, statistics, prices for non-crypto
+goods (real estate, retail, salaries), people, companies, news, etc.
+
+**Use specialized tools ONLY when the claim's domain matches:**
+- TradingMarket / TradingSignal — ONLY for cryptocurrency tickers (BTC, ETH, SOL, etc). Never for stocks, real estate, currencies, commodities outside crypto.
+- DefiLlamaProtocol / DefiLlamaYields / DefiLlamaPrice — ONLY for DeFi protocols, TVL, yields, on-chain token prices.
+- SearchX — ONLY for X.com / Twitter posts and accounts.
+- ExaAnswer — research questions where you want a synthesized answer with citations.
+- WebFetch — claims that quote a SPECIFIC URL the model already named.
+
+**Anti-patterns to never produce:**
+- Real-estate price → TradingMarket (TradingMarket is crypto-only — wrong domain)
+- Stock ticker → TradingMarket (also crypto-only — use WebSearch instead)
+- Generic news / statistics → TradingMarket (use WebSearch)
+- Person's biography → TradingMarket (use WebSearch)
+
+When unsure: name **WebSearch**. It's the safe default for factual grounding.
+
+## Format examples
+
+- Claim: "<the ungrounded part, quoted briefly>" → missing tool: WebSearch
+- Claim: "BTC at $67k" → missing tool: TradingMarket
+- Claim: "Westlake $/sqft is $719" → missing tool: WebSearch
+- Refusal: "<the refusal phrase, quoted briefly>" → should have called: WebSearch
 
 Empty line between verdict and list. No other text. No preamble. No apology. Be terse.`;
 // ─── Trigger policy ──────────────────────────────────────────────────────

package/dist/agent/loop.js

@@ -241,6 +241,39 @@ export function looksLikeGatewayErrorAsText(parts) {
         return { match: false, message: '' };
     return { match: true, message: m[1].trim() };
 }
+/**
+ * Domain check for the grounding-retry force-tool path. A specialized tool
+ * (TradingMarket, DefiLlama*, jupiter*, base0x*, SearchX) should only be
+ * pinned by tool_choice when the user prompt actually references that
+ * tool's domain — otherwise we let the smart generator pick from any tool.
+ *
+ * The motivating bug: a real-estate question ("可以还价 20% 吗") had its
+ * answer flagged as ungrounded for citing $/sqft figures. The cheap
+ * evaluator model picked TradingMarket as the missing tool because it
+ * was the first example in the evaluator prompt. Forcing TradingMarket
+ * (a crypto-only tool) on a housing question made the retry useless.
+ *
+ * This function returns false for specialized tools when the prompt has
+ * no matching domain keywords; the caller falls back to "any" tool.
+ * General-purpose tools (WebSearch, ExaSearch, ExaAnswer, WebFetch,
+ * ExaReadUrls) always pass — they're domain-agnostic.
+ */
+function isToolRelevantToPrompt(toolName, promptLower) {
+    // Crypto trading tools — need a ticker, "crypto", "coin", "swap", etc.
+    if (/^(Trading|DefiLlama|Jupiter|Base0x|Base0xGasless)/i.test(toolName)) {
+        return /\b(btc|eth|sol|xrp|doge|usdc|usdt|crypto|coin|token|defi|tvl|yield|swap|jupiter|uniswap|pump\.fun|solana|base chain|polygon|ethereum|币|代币|链上|做空|做多)\b/i.test(promptLower);
+    }
+    // X.com search — need an @handle, "twitter", "tweet", "X.com"
+    if (/^SearchX$/i.test(toolName) || /^PostToX$/i.test(toolName)) {
+        return /(@\w+|twitter|x\.com|tweet|推特)/i.test(promptLower);
+    }
+    // Image / video / music gen — need a creative-content request
+    if (/^(ImageGen|VideoGen|MusicGen)$/i.test(toolName)) {
+        return /\b(image|picture|photo|video|clip|music|song|generate|create|render|draw|画|图|视频|音乐|歌)\b/i.test(promptLower);
+    }
+    // General-purpose / file / shell tools — always relevant.
+    return true;
+}
 /**
  * Calculate backoff delay with jitter to avoid thundering herd.
  * Base: exponential (2^attempt * 1000ms), jitter: ±25%.
@@ -1349,11 +1382,23 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                             // Hard enforcement: set tool_choice so the model can't fabricate
                             // citations in lieu of running tools (the round-2 failure mode
                             // from the Tampa→Miami log). If the evaluator named exactly one
-                            // available tool, pin to it; otherwise force "any" tool use.
+                            // available tool AND that tool's domain matches the user's
+                            // prompt, pin to it; otherwise force "any" tool use and let
+                            // the generator pick the right one.
+                            //
+                            // Domain validation guards against the cheap evaluator model
+                            // hallucinating a wrong specialized tool (e.g., suggesting
+                            // TradingMarket for a real-estate question because the prompt
+                            // listed it as the first example tool). Specialized tools —
+                            // crypto trading, DeFi, swap quotes, X.com search — only get
+                            // pinned when their domain keywords appear in the user prompt;
+                            // otherwise we drop down to "any tool" and let the smart
+                            // generator model decide based on tool descriptions.
                             const namedTools = extractMissingToolNames(gResult);
                             const availableNames = new Set(buildCallToolDefs().map(t => t.name));
                             const matched = namedTools.filter(n => availableNames.has(n));
-                            if (matched.length === 1) {
+                            const promptForDomainCheck = (lastUserInput || '').toLowerCase();
+                            if (matched.length === 1 && isToolRelevantToPrompt(matched[0], promptForDomainCheck)) {
                                 forceToolChoiceNextRound = { type: 'tool', name: matched[0] };
                             }
                             else if (availableNames.size > 0) {

package/dist/tools/webfetch.js

@@ -58,6 +58,22 @@ async function execute(input, ctx) {
     if (!['http:', 'https:'].includes(parsed.protocol)) {
         return { output: `Error: only http/https URLs are supported`, isError: true };
     }
+    // ── Pre-flight: known anti-bot domains ──
+    // Sites that systematically block scripted access return 403 / 429 /
+    // captcha challenges to plain GET requests no matter what UA we send.
+    // Without this guard the model burns multiple turns retrying variations
+    // (Zillow → /research/austin-tx, /homedetails/X, /sold/Y...) that all
+    // 403 the same way, padding the step counter and the user's bill.
+    // Short-circuiting here returns a single actionable error instead.
+    const blocked = isBlockedDomain(parsed.hostname);
+    if (blocked) {
+        return {
+            output: `${parsed.hostname} systematically blocks automated fetch (${blocked.reason}). ` +
+                `Switch tools: ${blocked.alternative}. Don't retry this URL with WebFetch — ` +
+                `every variant of the same hostname returns the same block.`,
+            isError: true,
+        };
+    }
     const maxLen = Math.min(max_length ?? DEFAULT_MAX_LENGTH, MAX_BODY_BYTES);
     // ── YouTube special case ──
     // Plain HTML fetch on a youtube.com URL returns the SPA bundle (a wall of
@@ -108,8 +124,19 @@ async function execute(input, ctx) {
             redirect: 'follow',
         });
         if (!response.ok) {
+            // 403 / 429 from a domain not in the static block list often still
+            // means anti-bot — many sites tier their detection (first hit OK,
+            // subsequent ones blocked) or rely on UA fingerprinting. Surface
+            // this as an actionable hint so the model switches strategy
+            // instead of retrying the same URL with a different path.
+            const isAntiBot = response.status === 403 || response.status === 429 ||
+                response.status === 503;
+            const hint = isAntiBot
+                ? ` — ${parsed.hostname} likely blocks automated fetch. Try WebSearch for the same query, ` +
+                    `or fetch a different domain that publishes the same data.`
+                : '';
             return {
-                output: `HTTP ${response.status} ${response.statusText} for ${url}`,
+                output: `HTTP ${response.status} ${response.statusText} for ${url}${hint}`,
                 isError: true,
             };
         }
@@ -176,6 +203,76 @@ async function execute(input, ctx) {
         ctx.abortSignal.removeEventListener('abort', onAbort);
     }
 }
+const BLOCKED_DOMAINS = [
+    {
+        pattern: /(^|\.)zillow\.com$/i,
+        reason: '403 to all non-browser GETs',
+        alternative: 'use WebSearch for "Austin TX home price trends" or similar',
+    },
+    {
+        pattern: /(^|\.)redfin\.com$/i,
+        reason: '403 / captcha challenge to scripted requests',
+        alternative: 'use WebSearch with the property address or zip code',
+    },
+    {
+        pattern: /(^|\.)realtor\.com$/i,
+        reason: '403 / interstitial to non-browser UAs',
+        alternative: 'use WebSearch',
+    },
+    {
+        pattern: /(^|\.)linkedin\.com$/i,
+        reason: 'auth wall on every page',
+        alternative: 'use SearchX (X is the better discovery surface for the same people) or WebSearch',
+    },
+    {
+        pattern: /(^|\.)instagram\.com$/i,
+        reason: 'auth wall + 401 to public profile fetches',
+        alternative: 'use WebSearch for the username',
+    },
+    {
+        pattern: /(^|\.)facebook\.com$/i,
+        reason: 'auth wall on most public content',
+        alternative: 'use WebSearch',
+    },
+    {
+        pattern: /(^|\.)x\.com$/i,
+        reason: 'X.com requires authenticated API',
+        alternative: 'use SearchX (the dedicated X tool) instead of WebFetch',
+    },
+    {
+        pattern: /(^|\.)twitter\.com$/i,
+        reason: 'X.com requires authenticated API',
+        alternative: 'use SearchX (the dedicated X tool) instead of WebFetch',
+    },
+    {
+        pattern: /(^|\.)tiktok\.com$/i,
+        reason: 'returns SPA shell + JS challenge',
+        alternative: 'use WebSearch with the @username',
+    },
+    {
+        pattern: /(^|\.)reuters\.com$/i,
+        reason: 'paywall + bot detection',
+        alternative: 'use WebSearch which surfaces cached headlines',
+    },
+    {
+        pattern: /(^|\.)bloomberg\.com$/i,
+        reason: 'paywall + bot detection',
+        alternative: 'use WebSearch for the same story',
+    },
+    {
+        pattern: /(^|\.)wsj\.com$/i,
+        reason: 'paywall',
+        alternative: 'use WebSearch for the same story',
+    },
+];
+function isBlockedDomain(hostname) {
+    for (const entry of BLOCKED_DOMAINS) {
+        if (entry.pattern.test(hostname)) {
+            return { reason: entry.reason, alternative: entry.alternative };
+        }
+    }
+    return null;
+}
 // ─── YouTube transcript fetcher ─────────────────────────────────────────────
 // Fetches auto-generated or uploaded captions for a YouTube video by parsing
 // the watch-page's `ytInitialPlayerResponse` JSON. Pure HTTP, no deps. Saves

package/package.json

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