@blockrun/franklin 3.15.8 → 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/package.json

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