@blockrun/franklin 3.8.27 → 3.8.29

package/dist/agent/intent-prefetch.d.ts

@@ -51,9 +51,6 @@ export interface PrefetchResult {
      *  decide to skip injection entirely and let the model try its own way. */
     anyOk: boolean;
 }
-/** Parse the classifier's one-line reply. Very strict — any junk → null. */
-export declare function parseIntentReply(reply: string): Intent;
-export declare function classifyIntent(userInput: string, client: ModelClient): Promise<Intent>;
 /** Run the prefetch for an intent. Concurrent fan-out for price + news. */
 export declare function prefetchForIntent(intent: Intent, client: ModelClient): Promise<PrefetchResult | null>;
 /**

package/dist/agent/intent-prefetch.js

@@ -26,111 +26,16 @@
  * coordination gap (harness fetches, model synthesizes)."
  */
 import { getStockPrice, getPrice } from '../trading/data.js';
-// ─── Classifier ──────────────────────────────────────────────────────────
-// llama-4-maverick: same rationale as the router classifier — emits plain
-// text under tight max_tokens rather than routing through thinking blocks.
-const CLASSIFIER_MODEL = process.env.FRANKLIN_PREFETCH_MODEL || 'nvidia/llama-4-maverick';
-const CLASSIFIER_TIMEOUT_MS = 2_500;
-const CLASSIFIER_PROMPT = `You extract PREFETCH INTENT from a user message for a CLI agent that has live market-data tools.
-
-Your job: decide whether Franklin should fetch live data BEFORE the main model answers, so the answer is grounded in real data instead of model memory.
-
-Output one of:
-
-1. STOCK <TICKER> <MARKET> <NEWS>
-   When the user asks about a specific publicly-traded equity — by ticker (CRCL, AAPL, NVDA, 7203, 0005) or by company name that maps to one (Circle → CRCL, Apple → AAPL, Toyota → 7203, HSBC → 0005).
-   MARKET: us | hk | jp | kr | gb | de | fr | nl | ie | lu | cn | ca
-   NEWS: yes if the user also asks "why / what happened / analysis"; no otherwise.
-   Default market: us.
-
-2. CRYPTO <SYMBOL> <NEWS>
-   When the user asks about a cryptocurrency by symbol or name (BTC, ETH, Bitcoin, Ethereum, SOL, Solana).
-   NEWS: yes if asks why / recent news.
-
-3. NONE
-   Any other message: greetings, coding questions, general chat, questions about non-traded entities.
-
-Rules:
-- If the company could be either public or private and you're unsure, assume PUBLIC and emit STOCK with your best ticker guess. The tool will 404 gracefully if wrong.
-- One output line only. No explanation. No punctuation beyond what's shown.
-- Ticker in UPPERCASE.
-
-Examples:
-User: 帮我看看 CRCL 股票                → STOCK CRCL us no
-User: should I sell Circle stock?      → STOCK CRCL us no
-User: why did CRCL drop this week      → STOCK CRCL us yes
-User: BTC 现在价格                       → CRYPTO BTC no
-User: 为什么以太坊跌了                   → CRYPTO ETH yes
-User: Toyota 股价                        → STOCK 7203 jp no
-User: hi how are you                   → NONE
-User: fix the bug in foo.ts            → NONE
-
-Answer with just the one-line directive.`;
-/** Parse the classifier's one-line reply. Very strict — any junk → null. */
-export function parseIntentReply(reply) {
-    const line = reply.trim().split('\n')[0].trim().toUpperCase();
-    if (!line || line.startsWith('NONE'))
-        return null;
-    const stockMatch = line.match(/^STOCK\s+([A-Z0-9.\-]+)\s+([A-Z]{2})\s+(YES|NO)\b/);
-    if (stockMatch) {
-        const market = stockMatch[2].toLowerCase();
-        const validMarkets = ['us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca'];
-        if (!validMarkets.includes(market))
-            return null;
-        return {
-            kind: 'ticker',
-            symbol: stockMatch[1],
-            market: market,
-            assetClass: 'stock',
-            wantNews: stockMatch[3] === 'YES',
-        };
-    }
-    const cryptoMatch = line.match(/^CRYPTO\s+([A-Z0-9.\-]+)\s+(YES|NO)\b/);
-    if (cryptoMatch) {
-        return {
-            kind: 'ticker',
-            symbol: cryptoMatch[1],
-            assetClass: 'crypto',
-            wantNews: cryptoMatch[2] === 'YES',
-        };
-    }
-    return null;
-}
-export async function classifyIntent(userInput, client) {
-    if (process.env.FRANKLIN_NO_PREFETCH === '1')
-        return null;
-    const trimmed = userInput.trim();
-    // Only the cheapest gate — skip very short inputs that can't be a real
-    // market question ("hi", "ok", "thanks"). 6 chars covers those while
-    // still letting short-form Chinese / ticker prompts through, e.g.
-    // "BTC 价格" (6), "CRCL 多少" (7). Longer prompts all route to the LLM
-    // classifier, which decides NONE cheaply when not market-related.
-    if (trimmed.length < 6)
-        return null;
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), CLASSIFIER_TIMEOUT_MS);
-    try {
-        const result = await client.complete({
-            model: CLASSIFIER_MODEL,
-            system: CLASSIFIER_PROMPT,
-            messages: [{ role: 'user', content: trimmed.slice(0, 800) }],
-            tools: [],
-            max_tokens: 24,
-        }, ctrl.signal);
-        let raw = '';
-        for (const part of result.content) {
-            if (typeof part === 'object' && part.type === 'text' && part.text)
-                raw += part.text;
-        }
-        return parseIntentReply(raw);
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
+// ─── Intent source ──────────────────────────────────────────────────────
+//
+// Historical note: this file used to host its own LLM classifier
+// (`classifyIntent` + `parseIntentReply` + a ~40-line STOCK/CRYPTO/NONE
+// prompt). Since v3.8.27 the unified `turn-analyzer.ts` produces intent
+// as part of a single pre-turn call, and `loop.ts` reads
+// `turnAnalysis.intent` directly — the standalone classifier was dead
+// code with no remaining callers. Removed in v3.8.29. The TurnIntent
+// shape lives in turn-analyzer and is consumed by `prefetchForIntent`
+// below.
 // ─── Prefetch dispatcher ─────────────────────────────────────────────────
 function formatUsd(n) {
     if (!Number.isFinite(n))

package/dist/agent/loop.js

@@ -39,77 +39,12 @@ function replaceHistory(target, replacement) {
     target.splice(0, target.length, ...replacement);
 }
 // ─── Pushback detection ───────────────────────────────────────────────────
-// Cheap models plough forward when users correct them. This detects common
-// correction patterns so the agent can explicitly reset its approach.
-//
-// Precision-biased: we'd rather miss a real pushback than falsely trigger on
-// casual disagreement ("But how do I deploy?"). False positives pollute the
-// conversation and make the agent abandon working approaches unnecessarily.
-// STRONG patterns: high-precision correction language. Fires even on short input.
-const PUSHBACK_STRONG = [
-    /\b(that'?s?\s+(wrong|incorrect|not\s+right)|you'?re?\s+wrong)\b/i,
-    /\b(i\s+(said|told\s+you)|not\s+what\s+i)\b/i,
-    /^(stop|wrong|incorrect|try\s+again)\b/i,
-    /^(不对|不是|错了|再试|重来)/,
-];
-// WEAK patterns: common correction starters that also appear in casual speech.
-// Require a corroborating signal (see detectPushback) to count as pushback.
-const PUSHBACK_WEAK = [
-    /^(but|however|actually|wait|no+\b|hmm)\b/i,
-    /\b(we\s+are\s+using|the\s+correct|the\s+actual)\b/i,
-    /^(但是|其实|等等|停)/,
-];
-/**
- * True if the last assistant turn made a concrete claim worth pushing back
- * against: executed a tool, wrote code, or produced a non-trivial answer.
- * Casual assistant chatter doesn't warrant treating a "but" as a correction.
- */
-function lastAssistantHasClaim(history) {
-    for (let i = history.length - 1; i >= 0; i--) {
-        const msg = history[i];
-        if (msg.role !== 'assistant')
-            continue;
-        if (Array.isArray(msg.content)) {
-            for (const part of msg.content) {
-                const p = part;
-                if (p.type === 'tool_use')
-                    return true;
-                if (p.type === 'text' && typeof p.text === 'string' && p.text.trim().length >= 40) {
-                    return true;
-                }
-            }
-            return false;
-        }
-        if (typeof msg.content === 'string' && msg.content.trim().length >= 40)
-            return true;
-        return false;
-    }
-    return false;
-}
-function detectPushback(input, history) {
-    // Only count as pushback if there's a prior assistant turn to push back against.
-    if (history.length === 0)
-        return false;
-    if (!lastAssistantHasClaim(history))
-        return false;
-    const trimmed = input.trim();
-    if (trimmed.length === 0 || trimmed.length > 500)
-        return false;
-    // Strong patterns: direct correction language — fire immediately.
-    if (PUSHBACK_STRONG.some((re) => re.test(trimmed)))
-        return true;
-    // Weak patterns: only count if the message is short (< 120 chars) AND doesn't
-    // also contain a fresh request. A weak starter followed by "can you also X"
-    // or "please do Y" is scope addition, not correction.
-    if (PUSHBACK_WEAK.some((re) => re.test(trimmed))) {
-        if (trimmed.length > 120)
-            return false;
-        if (/\b(can you|could you|please|also|add|include)\b/i.test(trimmed))
-            return false;
-        return true;
-    }
-    return false;
-}
+// Formerly a pair of regex lists (PUSHBACK_STRONG / PUSHBACK_WEAK) plus a
+// claim-on-prior-turn check — ~70 lines of keyword heuristics. Replaced by
+// `turnAnalysis.isPushback` from `turn-analyzer.ts` (v3.8.27): the free
+// classifier reads the user's actual phrasing AND the prior assistant
+// reply and decides whether this turn is a correction. Zero keyword
+// allowlist, works across languages and phrasings the regex never covered.
 /**
  * Sanitize history: fix orphaned tool results AND inject missing results.
  *
@@ -456,20 +391,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     input = cmdResult.rewritten;
             }
         }
-        // ── Pushback detection ──
-        // When the user corrects us ("no", "but", "actually", "wrong"), we must throw
-        // away the previous plan and reconsider — not continue the failing approach.
-        // Without this signal, cheap models tend to plough forward with the same bad idea.
-        const pushbackSignal = detectPushback(input, history);
-        const effectiveInput = pushbackSignal
-            ? `${input}\n\n[SYSTEM NOTE] The user is correcting you. Your previous response was wrong or off-target. Do NOT continue the previous approach. Re-read the conversation, identify what specifically the user is correcting, and change your strategy. If the user pointed out a fact (e.g. "we are using X"), treat that fact as ground truth and rebuild your answer around it.`
-            : input;
         lastUserInput = input;
-        history.push({ role: 'user', content: effectiveInput });
+        // Push the user's clean message; any harness-injected annotations
+        // (pushback SYSTEM NOTE, prefetch context block) are applied AFTER
+        // the turn analyzer runs so they get driven by model-decided flags
+        // instead of keyword regex.
+        history.push({ role: 'user', content: input });
         turnCount++;
         toolGuard.startTurn();
-        // Persist the user's original message, not the injected SYSTEM NOTE scaffold.
-        // Resumed sessions should show what the user typed, not our internal prompt engineering.
         persistSessionMessage({ role: 'user', content: input });
         // ── Model recovery: try original model at the start of each new turn ──
         // If we fell back to a free model last turn due to a transient error, try original again.
@@ -595,6 +524,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         catch {
             // Analyzer is best-effort; ignore.
         }
+        // ── Pushback annotation ─────────────────────────────────────────
+        // If the analyzer judged this turn as a user correction of the
+        // previous answer, inject a SYSTEM NOTE into the user message so the
+        // model resets its approach rather than doubling down. Replaces the
+        // former PUSHBACK_STRONG / PUSHBACK_WEAK regex lists — model-decided,
+        // no keyword allowlist to rot.
+        if (turnAnalysis?.isPushback) {
+            const lastIdx = history.length - 1;
+            const last = history[lastIdx];
+            if (last && last.role === 'user' && typeof last.content === 'string') {
+                history[lastIdx] = {
+                    role: 'user',
+                    content: `${last.content}\n\n[SYSTEM NOTE] The user is correcting you. Your previous response was wrong or off-target. Do NOT continue the previous approach. Re-read the conversation, identify what specifically the user is correcting, and change your strategy. If the user pointed out a fact (e.g. "we are using X"), treat that fact as ground truth and rebuild your answer around it.`,
+                };
+            }
+        }
         // ── Proactive prefetch ────────────────────────────────────────────
         // Uses the intent the analyzer already extracted. Skips the separate
         // prefetch-classifier call that previously ran here.
@@ -762,7 +707,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 routingConfidence = routing.confidence;
                 routingSavings = routing.savings;
                 lastRoutedModel = routing.model;
-                lastRoutedCategory = routing.signals[0] || '';
+                lastRoutedCategory = routing.category || '';
                 if (loopCount === 1) {
                     onEvent({
                         kind: 'text_delta',
@@ -773,8 +718,12 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // Update token estimation model for more accurate byte-per-token ratio
             setEstimationModel(resolvedModel);
             // ── Plan-then-execute: detect and activate ──
+            // `needsPlanning` flag comes from turn-analyzer (one-word LLM decision
+            // on the user's original prompt). shouldPlan still guards env / profile /
+            // ultrathink / per-session overrides — those are operator policy, not
+            // model decisions.
             if (loopCount === 1 && !planActive && routingProfile &&
-                shouldPlan(routingTier, routingProfile, lastUserInput, !!config.ultrathink, !!config.planDisabled)) {
+                shouldPlan(routingProfile, !!config.ultrathink, !!config.planDisabled, turnAnalysis?.needsPlanning ?? false)) {
                 planActive = true;
                 planPlannerModel = resolvedModel;
                 planExecutorModel = getExecutorModel(routingProfile);

package/dist/agent/planner.d.ts

@@ -7,13 +7,19 @@
  * Flow: detect complexity → plan with strong model → execute with cheap model
  *       → escalate back to strong model if executor gets stuck
  */
-import type { Tier, RoutingProfile } from '../router/index.js';
+import type { RoutingProfile } from '../router/index.js';
 /**
  * Should this task use plan-then-execute?
- * Returns true only for complex, multi-step tasks where the savings justify
- * the overhead of an extra planning call.
+ *
+ * Replaces the former AGENTIC_KEYWORDS / MULTI_STEP_PATTERN regex heuristics
+ * with a single read of `turnAnalysis.needsPlanning`. The free model judged
+ * whether the task is substantive-multi-step from the user's actual phrasing,
+ * no keyword allowlist to maintain.
+ *
+ * Environment gates (opt-in / opt-out / profile / ultrathink / session
+ * override) remain — those are operator decisions, not model decisions.
  */
-export declare function shouldPlan(tier: Tier | undefined, profile: RoutingProfile | undefined, userText: string, ultrathink: boolean, planDisabled: boolean): boolean;
+export declare function shouldPlan(profile: RoutingProfile | undefined, ultrathink: boolean, planDisabled: boolean, analyzerSaysNeedsPlanning: boolean): boolean;
 /**
  * Returns the planning system prompt section.
  * Injected alongside the normal system prompt during the planning call.

package/dist/agent/planner.js

@@ -7,53 +7,38 @@
  * Flow: detect complexity → plan with strong model → execute with cheap model
  *       → escalate back to strong model if executor gets stuck
  */
-// ─── Agentic keywords that suggest multi-step work ───────────────────────
-const AGENTIC_KEYWORDS = /\b(implement|refactor|build|fix|debug|migrate|deploy|create|add|remove|update|restructure|extract|rewrite|optimize|convert|integrate|setup|configure)\b/i;
-const MULTI_STEP_PATTERN = /first.*then|step\s+\d|\d+\.\s|and\s+then|after\s+that|next\s*,|finally\b/i;
 // ─── Detection ───────────────────────────────────────────────────────────
 /**
  * Should this task use plan-then-execute?
- * Returns true only for complex, multi-step tasks where the savings justify
- * the overhead of an extra planning call.
+ *
+ * Replaces the former AGENTIC_KEYWORDS / MULTI_STEP_PATTERN regex heuristics
+ * with a single read of `turnAnalysis.needsPlanning`. The free model judged
+ * whether the task is substantive-multi-step from the user's actual phrasing,
+ * no keyword allowlist to maintain.
+ *
+ * Environment gates (opt-in / opt-out / profile / ultrathink / session
+ * override) remain — those are operator decisions, not model decisions.
  */
-export function shouldPlan(tier, profile, userText, ultrathink, planDisabled) {
-    // Default: plan-then-execute is OFF (v3.8.18). Observed failure: router
-    // correctly picks Sonnet for a "should I sell CRCL" prompt, but the
-    // executor swap downgrades actual execution to gemini-2.5-flash, which
-    // then answers from memory instead of calling TradingMarket / ExaAnswer.
-    // The cheap-executor pattern was load-bearing for Sonnet 4.0-era models;
-    // Opus 4.7 / Sonnet 4.6 handle multi-step tool use coherently in a
-    // single pass, so the two-call path is pure overhead — and it actively
-    // hurts when the executor is weaker than the planner.
-    // Opt back in with FRANKLIN_PLAN=1 (for experiments / ablation).
+export function shouldPlan(profile, ultrathink, planDisabled, analyzerSaysNeedsPlanning) {
+    // Default: plan-then-execute is OFF (since v3.8.18). The cheap-executor
+    // pattern was load-bearing for Sonnet-4.0-era models but Opus 4.7 /
+    // Sonnet 4.6 handle multi-step tool use in a single pass. Opt in with
+    // FRANKLIN_PLAN=1 for ablation / experiments.
     if (process.env.FRANKLIN_PLAN !== '1')
         return false;
-    // Legacy env opt-out — still honored for users who set it previously.
+    // Legacy env opt-out still honored for users who set it previously.
     if (process.env.FRANKLIN_NOPLAN === '1')
         return false;
-    // User disabled planning for this session
+    // Per-session / per-turn overrides from the agent surface.
     if (planDisabled)
         return false;
-    // Ultrathink already provides deep reasoning
     if (ultrathink)
-        return false;
-    // Only auto or premium profiles (eco/free are cost-constrained)
+        return false; // ultrathink already provides deep reasoning
+    // Only auto / premium profiles — eco / free are cost-constrained.
     if (profile !== 'auto' && profile !== 'premium')
         return false;
-    // Explicit multi-step language always plans, regardless of tier / length
-    // ("first ... then ...", "step 1 ... step 2 ...", numbered lists, etc.)
-    if (MULTI_STEP_PATTERN.test(userText))
-        return true;
-    // Planning is high-ROI on COMPLEX / REASONING tiers for agentic verbs,
-    // even when the prompt is short ("refactor the wallet module", "migrate to TS")
-    if (tier === 'COMPLEX' || tier === 'REASONING') {
-        return AGENTIC_KEYWORDS.test(userText) || userText.length >= 60;
-    }
-    // On MEDIUM tier: plan only if long AND agentic
-    if (tier === 'MEDIUM' && userText.length >= 120 && AGENTIC_KEYWORDS.test(userText)) {
-        return true;
-    }
-    return false;
+    // Final decision comes from the turn analyzer's boolean flag.
+    return analyzerSaysNeedsPlanning;
 }
 // ─── Planning Prompt ─────────────────────────────────────────────────────
 /**

package/dist/router/index.d.ts

@@ -9,6 +9,7 @@
  * and picks the model with the best quality-to-cost ratio for that category.
  * Local Elo adjustments personalize routing per user over time.
  */
+import { type Category } from './categories.js';
 export type Tier = 'SIMPLE' | 'MEDIUM' | 'COMPLEX' | 'REASONING';
 export type RoutingProfile = 'auto' | 'eco' | 'premium' | 'free';
 export interface RoutingResult {
@@ -17,6 +18,7 @@ export interface RoutingResult {
     confidence: number;
     signals: string[];
     savings: number;
+    category?: Category;
 }
 export type TierClassifier = (prompt: string) => Promise<Tier | null>;
 /**

package/dist/router/index.js

@@ -265,7 +265,8 @@ function classicRouteRequest(prompt, profile) {
     }
     const model = tierConfigs[tier].primary;
     const savings = computeSavings(model);
-    return { model, tier, confidence, signals, savings };
+    const category = detectCategory(prompt, loadLearnedWeights()?.category_keywords).category;
+    return { model, tier, confidence, signals, savings, category };
 }
 // ─── LLM-based classifier ───
 //
@@ -385,12 +386,14 @@ export async function routeRequestAsync(prompt, profile = 'auto', classify = llm
         default: tierConfigs = AUTO_TIERS;
     }
     const model = tierConfigs[tier].primary;
+    const category = detectCategory(prompt, loadLearnedWeights()?.category_keywords).category;
     return {
         model,
         tier,
         confidence: 0.85, // LLM classification — medium-high confidence
         signals: ['llm-classified'],
         savings: computeSavings(model),
+        category,
     };
 }
 /**
@@ -481,6 +484,7 @@ export function routeRequest(prompt, profile = 'auto') {
                 confidence,
                 signals: [category],
                 savings,
+                category,
             };
         }
         // Fall through to classic if selectModel returns null (no candidates for category)

package/package.json

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