@blockrun/franklin 3.8.26 → 3.8.28

package/dist/agent/loop.js

@@ -21,12 +21,13 @@ import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
-import { routeRequestAsync, parseRoutingProfile } from '../router/index.js';
+import { routeRequestAsync, resolveTierToModel, parseRoutingProfile } from '../router/index.js';
 import { recordOutcome } from '../router/local-elo.js';
 import { shouldPlan, getPlanningPrompt, getExecutorModel, isExecutorStuck, toolCallSignature } from './planner.js';
 import { shouldVerify, runVerification } from './verification.js';
 import { shouldCheckGrounding, checkGrounding, renderGroundingFollowup, buildGroundingRetryInstruction, } from './evaluator.js';
-import { augmentUserMessage, classifyIntent, prefetchForIntent } from './intent-prefetch.js';
+import { augmentUserMessage, prefetchForIntent } from './intent-prefetch.js';
+import { analyzeTurn } from './turn-analyzer.js';
 import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions, loadSessionHistory, loadSessionMeta, } from '../session/storage.js';
 /**
  * Atomically replace all elements in a history array.
@@ -38,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.
  *
@@ -455,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.
@@ -552,24 +482,74 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         const MAX_TINY_RESPONSES = 2; // Break after N tiny responses — if 2 calls return near-empty, something is wrong
         let turnSpend = 0; // Cost spent this user turn (USD)
         const MAX_TURN_SPEND_USD = 0.25; // Hard circuit breaker per user message (lowered — user wallets are real money)
+        // ── Turn analysis (one classifier call, drives routing + prefetch) ──
+        // Single LLM pass that answers every routing-adjacent question the
+        // harness needs BEFORE the main model runs: tier, ticker intent,
+        // pushback, planning need, live-data signal. Replaces what used to be
+        // two separate classifier calls (router + prefetch) plus keyword rule
+        // engines for pushback / shouldPlan. Safe-defaults on any failure so
+        // the main flow never blocks on it.
+        let turnAnalysis = null;
+        try {
+            // Anchor 1: the user's current message (already in lastUserInput).
+            // Anchor 2: first chunk of the previous assistant reply — gives the
+            // analyzer enough context to resolve deictic follow-ups like "那 AAPL 呢".
+            const lastAssistantText = (() => {
+                const prior = [...history.slice(0, -1)].reverse()
+                    .find((m) => m.role === 'assistant');
+                if (!prior)
+                    return '';
+                if (typeof prior.content === 'string')
+                    return prior.content;
+                if (!Array.isArray(prior.content))
+                    return '';
+                return prior.content
+                    .filter(p => p.type === 'text')
+                    .map(p => p.text ?? '')
+                    .join(' ');
+            })();
+            // Anchor 3: the very first user message in this session (session goal).
+            const sessionGoal = (() => {
+                const first = history.find((m) => m.role === 'user');
+                if (!first)
+                    return '';
+                return typeof first.content === 'string' ? first.content : '';
+            })();
+            turnAnalysis = await analyzeTurn(input, {
+                lastAssistantText,
+                sessionGoal,
+                client,
+            });
+        }
+        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 ────────────────────────────────────────────
-        // Before the main model gets a chance to answer a live-world question
-        // from stale training data, the harness detects ticker / price / news
-        // intent and fetches the data itself. Result is prepended to the user's
-        // message so the model sees it as ground truth for this turn. This
-        // makes the answer tool-grounded regardless of the model's willingness
-        // to call tools on its own — important for models with strong
-        // refusal priors on financial data.
+        // Uses the intent the analyzer already extracted. Skips the separate
+        // prefetch-classifier call that previously ran here.
         try {
-            const intent = await classifyIntent(input, client);
-            if (intent) {
-                const prefetch = await prefetchForIntent(intent, client);
+            if (turnAnalysis?.intent) {
+                const prefetch = await prefetchForIntent(turnAnalysis.intent, client);
                 if (prefetch && prefetch.anyOk) {
                     if (config.showPrefetchStatus !== false) {
                         onEvent({ kind: 'text_delta', text: `\n${prefetch.statusLine}\n\n` });
                     }
-                    // Augment the last user message in history (NOT lastUserInput,
-                    // which /retry restores — that should remain the user's original).
                     const lastIdx = history.length - 1;
                     const last = history[lastIdx];
                     if (last && last.role === 'user' && typeof last.content === 'string') {
@@ -579,8 +559,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }
         }
         catch {
-            // Prefetch is best-effort — if the classifier or any fetch trips,
-            // fall through and let the main loop do its own thing.
+            // Prefetch is best-effort — never block the main loop.
         }
         // Agent loop for this user message
         while (loopCount < maxTurns) {
@@ -711,28 +690,24 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 sessionId,
             });
             // ── Router: resolve routing profiles to concrete models ──
-            // Classifier always sees the user's ORIGINAL prompt for this turn —
-            // never the `[GROUNDING CHECK FAILED]` / `[VERIFICATION FAILED]` /
-            // pushback-annotated variants the loop injects mid-turn. Same input
-            // across iterations → same tier → stable resolved model. Stops the
-            // failure mode where a retry message classified as SIMPLE dropped
-            // a COMPLEX task down to gemini mid-way.
+            // Uses the tier already decided by the turn-analyzer — one LLM call
+            // up-front rather than a separate classifier here. Fallback to the
+            // stand-alone classifier if analyzer wasn't available.
             const routingProfile = parseRoutingProfile(config.model);
             let resolvedModel = config.model;
             let routingTier;
             let routingConfidence;
             let routingSavings;
             if (routingProfile) {
-                const userText = lastUserInput || '';
-                const routing = await routeRequestAsync(userText, routingProfile);
+                const routing = turnAnalysis
+                    ? resolveTierToModel(turnAnalysis.tier, routingProfile)
+                    : await routeRequestAsync(lastUserInput || '', routingProfile);
                 resolvedModel = routing.model;
                 routingTier = routing.tier;
                 routingConfidence = routing.confidence;
                 routingSavings = routing.savings;
                 lastRoutedModel = routing.model;
                 lastRoutedCategory = routing.signals[0] || '';
-                // Surface the routing decision on the first iteration so the user
-                // sees which concrete model got picked, not just "auto".
                 if (loopCount === 1) {
                     onEvent({
                         kind: 'text_delta',
@@ -743,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/agent/turn-analyzer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Turn analyzer — one LLM call per turn that answers every routing-adjacent
+ * question the harness needs to make BEFORE the main model runs.
+ *
+ * Why this exists:
+ * Prior versions called separate classifiers for routing (what tier?) and
+ * prefetch (is there a ticker?). Each additional harness decision tempted
+ * us to add yet another classifier call (pushback? plan? needs-grounding?).
+ * Each call adds ~500-800ms of serial latency; stack six of them and the
+ * user waits multiple seconds before the main model even starts.
+ *
+ * This consolidates every LLM-decidable pre-turn question into a single
+ * call with a structured JSON response. Net result: 1 classifier call per
+ * turn (was 2), replacing multiple keyword rule engines (pushback regex,
+ * shouldPlan keyword list, shouldCheckGrounding length gates).
+ *
+ * Principle: harness orchestrates, models decide. No keyword allowlists,
+ * no length thresholds, no regex heuristics encoded in TypeScript.
+ *
+ * Budget discipline:
+ * - Input capped at ~1500 chars across three anchors (current, prev reply,
+ *   session goal). Never the full history.
+ * - Output capped at 128 tokens (compact single-line JSON).
+ * - 2.5s hard timeout; on any failure, conservative default returned so
+ *   the main flow never blocks.
+ * - 30s in-memory cache keyed on the three anchors so back-to-back near-
+ *   identical turns don't re-pay the latency.
+ */
+import type { ModelClient } from './llm.js';
+import type { MarketCode } from '../trading/providers/standard-models.js';
+import type { Tier } from '../router/index.js';
+export interface TurnIntent {
+    kind: 'ticker';
+    symbol: string;
+    assetClass: 'stock' | 'crypto';
+    market?: MarketCode;
+    wantNews: boolean;
+}
+export interface TurnAnalysis {
+    tier: Tier;
+    intent: TurnIntent | null;
+    /** True for substantive multi-step engineering tasks worth a plan-then-execute split. */
+    needsPlanning: boolean;
+    /** True when the user is correcting the previous assistant turn. */
+    isPushback: boolean;
+    /** True when the user asks for current prices / today's state / recent news. */
+    asksForLiveData: boolean;
+}
+/** Test / reset helper. */
+export declare function clearAnalyzerCache(): void;
+/**
+ * Parse the analyzer's JSON output. Returns null on any structural issue;
+ * caller falls back to conservative defaults.
+ */
+export declare function parseAnalysis(raw: string): TurnAnalysis | null;
+export interface AnalyzeOpts {
+    lastAssistantText?: string;
+    sessionGoal?: string;
+    client: ModelClient;
+    model?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Analyze one turn. Always returns a TurnAnalysis — never throws. On any
+ * failure path (timeout, parse error, empty response, gateway down) the
+ * conservative default is returned so the main flow proceeds without the
+ * harness's pre-decisions. The analyzer is a quality booster, not a
+ * correctness requirement.
+ */
+export declare function analyzeTurn(userInput: string, opts: AnalyzeOpts): Promise<TurnAnalysis>;

package/dist/agent/turn-analyzer.js

@@ -0,0 +1,297 @@
+/**
+ * Turn analyzer — one LLM call per turn that answers every routing-adjacent
+ * question the harness needs to make BEFORE the main model runs.
+ *
+ * Why this exists:
+ * Prior versions called separate classifiers for routing (what tier?) and
+ * prefetch (is there a ticker?). Each additional harness decision tempted
+ * us to add yet another classifier call (pushback? plan? needs-grounding?).
+ * Each call adds ~500-800ms of serial latency; stack six of them and the
+ * user waits multiple seconds before the main model even starts.
+ *
+ * This consolidates every LLM-decidable pre-turn question into a single
+ * call with a structured JSON response. Net result: 1 classifier call per
+ * turn (was 2), replacing multiple keyword rule engines (pushback regex,
+ * shouldPlan keyword list, shouldCheckGrounding length gates).
+ *
+ * Principle: harness orchestrates, models decide. No keyword allowlists,
+ * no length thresholds, no regex heuristics encoded in TypeScript.
+ *
+ * Budget discipline:
+ * - Input capped at ~1500 chars across three anchors (current, prev reply,
+ *   session goal). Never the full history.
+ * - Output capped at 128 tokens (compact single-line JSON).
+ * - 2.5s hard timeout; on any failure, conservative default returned so
+ *   the main flow never blocks.
+ * - 30s in-memory cache keyed on the three anchors so back-to-back near-
+ *   identical turns don't re-pay the latency.
+ */
+/**
+ * Safe default returned when the analyzer call fails (timeout, parse error,
+ * gateway down). Chosen to be neutral:
+ *   - MEDIUM tier → router picks a capable mid-tier model, not the cheapest
+ *   - no intent → prefetch skips
+ *   - all booleans false → downstream gates don't fire speculatively
+ * The main-flow still runs; the harness just loses its per-turn pre-decisions.
+ */
+const CONSERVATIVE_DEFAULT = {
+    tier: 'MEDIUM',
+    intent: null,
+    needsPlanning: false,
+    isPushback: false,
+    asksForLiveData: false,
+};
+// ─── Input budget ───────────────────────────────────────────────────────
+const MAX_CURRENT_CHARS = 800;
+const MAX_PREV_REPLY_CHARS = 300;
+const MAX_GOAL_CHARS = 200;
+const TIMEOUT_MS = 2_500;
+const MAX_ANALYZER_TOKENS = 128;
+const CACHE_TTL_MS = 30_000;
+const CACHE_MAX_SIZE = 64;
+// ─── Analyzer prompt ────────────────────────────────────────────────────
+//
+// Design: one compact prompt, a few precise examples, instruct the model to
+// emit a single-line JSON. Maverick (the classifier backbone since v3.8.23)
+// reliably produces plain-text structured output under tight max_tokens,
+// unlike thinking-first models that leave text empty.
+const ANALYZER_MODEL_DEFAULT = process.env.FRANKLIN_ANALYZER_MODEL || 'nvidia/llama-4-maverick';
+const ANALYZER_SYSTEM = `You analyze ONE user message for Franklin's routing + prefetch harness. Output ONE LINE of compact JSON — no explanation, no markdown, no code fences.
+
+## Fields
+
+tier: "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING"
+  SIMPLE    — greetings, arithmetic, trivia, short factual Q
+  MEDIUM    — targeted code edits, simple lookups, summaries, single-tool tasks
+  COMPLEX   — analysis, recommendations, research questions needing live data, multi-step tool use
+  REASONING — formal proofs, derivations, deep logic, multi-variable optimization
+  NEVER route ticker / price / stock / "should I" / "why did" questions below COMPLEX.
+
+intent: null OR {"kind":"ticker","symbol":"...","assetClass":"stock"|"crypto","market":"us"|"hk"|"jp"|"kr"|"gb"|"de"|"fr"|"nl"|"ie"|"lu"|"cn"|"ca","wantNews":true|false}
+  Set when the user names a ticker, a publicly-traded company, or a cryptocurrency.
+  Omit "market" for crypto; default "us" for stocks if unclear.
+  wantNews: true if the user asks why / what happened / analyze. false for plain price lookup.
+
+needsPlanning: true | false
+  true only for substantive multi-step engineering tasks (build X, refactor Y across many files).
+
+isPushback: true | false
+  true when the user is correcting / disagreeing with the previous assistant turn.
+
+asksForLiveData: true | false
+  true when the user asks for a current price, today's news, or any live-world state.
+
+## Context anchors in input
+
+[CURRENT]    user's message this turn (primary signal)
+[PREV_REPLY] last assistant reply, first ~300 chars (for follow-up references: "那 AAPL 呢", "and that one?", "the other ticker")
+[GOAL]       original session prompt, first ~200 chars
+
+If [CURRENT] uses a deictic ("it", "that", "那", "这个"), resolve intent/tier from [PREV_REPLY] or [GOAL].
+
+## Examples
+
+Input:
+[CURRENT] hi
+Output: {"tier":"SIMPLE","intent":null,"needsPlanning":false,"isPushback":false,"asksForLiveData":false}
+
+Input:
+[CURRENT] should I sell CRCL and why did it drop
+Output: {"tier":"COMPLEX","intent":{"kind":"ticker","symbol":"CRCL","assetClass":"stock","market":"us","wantNews":true},"needsPlanning":false,"isPushback":false,"asksForLiveData":true}
+
+Input:
+[CURRENT] 那 AAPL 呢
+[PREV_REPLY] CRCL 当前价格 $96.18，最近因 Drift 诉讼下跌...
+Output: {"tier":"COMPLEX","intent":{"kind":"ticker","symbol":"AAPL","assetClass":"stock","market":"us","wantNews":false},"needsPlanning":false,"isPushback":false,"asksForLiveData":true}
+
+Input:
+[CURRENT] BTC 为什么跌了
+Output: {"tier":"COMPLEX","intent":{"kind":"ticker","symbol":"BTC","assetClass":"crypto","wantNews":true},"needsPlanning":false,"isPushback":false,"asksForLiveData":true}
+
+Input:
+[CURRENT] 不对，你应该看 NVDA 不是 AAPL
+[PREV_REPLY] AAPL 当前价格 $186.42
+Output: {"tier":"COMPLEX","intent":{"kind":"ticker","symbol":"NVDA","assetClass":"stock","market":"us","wantNews":false},"needsPlanning":false,"isPushback":true,"asksForLiveData":true}
+
+Input:
+[CURRENT] refactor the wallet module to use typed errors across all call sites
+Output: {"tier":"MEDIUM","intent":null,"needsPlanning":true,"isPushback":false,"asksForLiveData":false}
+
+Input:
+[CURRENT] prove that sqrt(2) is irrational
+Output: {"tier":"REASONING","intent":null,"needsPlanning":false,"isPushback":false,"asksForLiveData":false}
+
+Output the JSON only. One line. No trailing text.`;
+const cache = new Map();
+/** Simple deterministic string hash for cache keys — no crypto, just bucketing. */
+function hashKey(parts) {
+    const joined = parts.join('
');
+    let h = 0;
+    for (let i = 0; i < joined.length; i++) {
+        h = ((h << 5) - h + joined.charCodeAt(i)) | 0;
+    }
+    return String(h);
+}
+function cacheGet(key) {
+    const hit = cache.get(key);
+    if (!hit)
+        return null;
+    if (Date.now() > hit.expiresAt) {
+        cache.delete(key);
+        return null;
+    }
+    return hit.value;
+}
+function cacheSet(key, value) {
+    if (cache.size >= CACHE_MAX_SIZE) {
+        // Evict oldest by insertion order (Map preserves it).
+        const firstKey = cache.keys().next().value;
+        if (firstKey)
+            cache.delete(firstKey);
+    }
+    cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+/** Test / reset helper. */
+export function clearAnalyzerCache() {
+    cache.clear();
+}
+// ─── Parsing ────────────────────────────────────────────────────────────
+const VALID_TIERS = new Set(['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING']);
+const VALID_MARKETS = new Set([
+    'us', 'hk', 'jp', 'kr', 'gb', 'de', 'fr', 'nl', 'ie', 'lu', 'cn', 'ca',
+]);
+function validateIntent(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (o.kind !== 'ticker')
+        return null;
+    const symbol = typeof o.symbol === 'string' ? o.symbol.trim().toUpperCase() : '';
+    if (!symbol || !/^[A-Z0-9.\-]+$/.test(symbol))
+        return null;
+    const assetClass = o.assetClass === 'stock' || o.assetClass === 'crypto' ? o.assetClass : null;
+    if (!assetClass)
+        return null;
+    let market;
+    if (assetClass === 'stock') {
+        const m = typeof o.market === 'string' ? o.market.toLowerCase() : 'us';
+        market = VALID_MARKETS.has(m) ? m : 'us';
+    }
+    return {
+        kind: 'ticker',
+        symbol,
+        assetClass,
+        ...(market ? { market } : {}),
+        wantNews: Boolean(o.wantNews),
+    };
+}
+/**
+ * Parse the analyzer's JSON output. Returns null on any structural issue;
+ * caller falls back to conservative defaults.
+ */
+export function parseAnalysis(raw) {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        return null;
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        const tier = typeof parsed.tier === 'string' && VALID_TIERS.has(parsed.tier)
+            ? parsed.tier
+            : null;
+        if (!tier)
+            return null;
+        return {
+            tier,
+            intent: validateIntent(parsed.intent),
+            needsPlanning: Boolean(parsed.needsPlanning),
+            isPushback: Boolean(parsed.isPushback),
+            asksForLiveData: Boolean(parsed.asksForLiveData),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Input assembly ─────────────────────────────────────────────────────
+/** Build the bounded input the analyzer sees. Never sends raw history. */
+function buildAnalyzerInput(userInput, lastAssistantText, sessionGoal) {
+    const parts = [];
+    parts.push(`[CURRENT]`);
+    parts.push(userInput.trim().slice(0, MAX_CURRENT_CHARS));
+    if (lastAssistantText && lastAssistantText.trim().length > 0) {
+        // First paragraph is usually the most informative. Strip markdown chrome.
+        const cleaned = lastAssistantText.trim()
+            .replace(/^#+\s+/gm, '')
+            .replace(/\*\*/g, '');
+        parts.push('');
+        parts.push('[PREV_REPLY]');
+        parts.push(cleaned.slice(0, MAX_PREV_REPLY_CHARS));
+    }
+    if (sessionGoal && sessionGoal.trim().length > 0 && sessionGoal.trim() !== userInput.trim()) {
+        parts.push('');
+        parts.push('[GOAL]');
+        parts.push(sessionGoal.trim().slice(0, MAX_GOAL_CHARS));
+    }
+    return parts.join('\n');
+}
+/**
+ * Analyze one turn. Always returns a TurnAnalysis — never throws. On any
+ * failure path (timeout, parse error, empty response, gateway down) the
+ * conservative default is returned so the main flow proceeds without the
+ * harness's pre-decisions. The analyzer is a quality booster, not a
+ * correctness requirement.
+ */
+export async function analyzeTurn(userInput, opts) {
+    if (process.env.FRANKLIN_NO_ANALYZER === '1')
+        return CONSERVATIVE_DEFAULT;
+    const trimmed = userInput.trim();
+    if (!trimmed)
+        return CONSERVATIVE_DEFAULT;
+    const prevReply = opts.lastAssistantText?.trim().slice(0, MAX_PREV_REPLY_CHARS) || '';
+    const goal = opts.sessionGoal?.trim().slice(0, MAX_GOAL_CHARS) || '';
+    const key = hashKey([trimmed.slice(0, MAX_CURRENT_CHARS), prevReply, goal]);
+    const cached = cacheGet(key);
+    if (cached)
+        return cached;
+    const input = buildAnalyzerInput(trimmed, prevReply || undefined, goal || undefined);
+    const timeoutCtrl = new AbortController();
+    const timer = setTimeout(() => timeoutCtrl.abort(), TIMEOUT_MS);
+    const signal = opts.signal ? anySignal([opts.signal, timeoutCtrl.signal]) : timeoutCtrl.signal;
+    try {
+        const result = await opts.client.complete({
+            model: opts.model || ANALYZER_MODEL_DEFAULT,
+            system: ANALYZER_SYSTEM,
+            messages: [{ role: 'user', content: input }],
+            tools: [],
+            max_tokens: MAX_ANALYZER_TOKENS,
+        }, signal);
+        let raw = '';
+        for (const part of result.content) {
+            if (typeof part === 'object' && part.type === 'text' && part.text)
+                raw += part.text;
+        }
+        const parsed = parseAnalysis(raw);
+        const final = parsed || CONSERVATIVE_DEFAULT;
+        if (parsed)
+            cacheSet(key, parsed);
+        return final;
+    }
+    catch {
+        return CONSERVATIVE_DEFAULT;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Compose two AbortSignals into one — aborts when either source aborts. */
+function anySignal(signals) {
+    const ctrl = new AbortController();
+    for (const s of signals) {
+        if (s.aborted) {
+            ctrl.abort();
+            break;
+        }
+        s.addEventListener('abort', () => ctrl.abort(), { once: true });
+    }
+    return ctrl.signal;
+}

package/dist/router/index.d.ts

@@ -32,6 +32,16 @@ export declare function llmClassifyRequest(prompt: string): Promise<Tier | null>
  * the concrete model; the classifier only picks the TIER.
  */
 export declare function routeRequestAsync(prompt: string, profile?: RoutingProfile, classify?: TierClassifier): Promise<RoutingResult>;
+/**
+ * Map a pre-classified tier to a concrete model + savings using the profile's
+ * tier table. No classifier call — assumes the caller already decided the
+ * tier (typically via the turn-analyzer, which rolls tier classification in
+ * with intent / pushback / planning decisions in one LLM call).
+ *
+ * Use this when you have a tier already. Use `routeRequestAsync` when you
+ * need the classifier to produce the tier.
+ */
+export declare function resolveTierToModel(tier: Tier, profile?: RoutingProfile): RoutingResult;
 export declare function routeRequest(prompt: string, profile?: RoutingProfile): RoutingResult;
 /**
  * Get fallback models for a tier

package/dist/router/index.js

@@ -393,6 +393,45 @@ export async function routeRequestAsync(prompt, profile = 'auto', classify = llm
         savings: computeSavings(model),
     };
 }
+/**
+ * Map a pre-classified tier to a concrete model + savings using the profile's
+ * tier table. No classifier call — assumes the caller already decided the
+ * tier (typically via the turn-analyzer, which rolls tier classification in
+ * with intent / pushback / planning decisions in one LLM call).
+ *
+ * Use this when you have a tier already. Use `routeRequestAsync` when you
+ * need the classifier to produce the tier.
+ */
+export function resolveTierToModel(tier, profile = 'auto') {
+    // Free profile short-circuits — everything routes to a single free model.
+    if (profile === 'free') {
+        return {
+            model: 'nvidia/glm-4.7',
+            tier: 'SIMPLE',
+            confidence: 1.0,
+            signals: ['free-profile'],
+            savings: 1.0,
+        };
+    }
+    let tierConfigs;
+    switch (profile) {
+        case 'eco':
+            tierConfigs = ECO_TIERS;
+            break;
+        case 'premium':
+            tierConfigs = PREMIUM_TIERS;
+            break;
+        default: tierConfigs = AUTO_TIERS;
+    }
+    const model = tierConfigs[tier].primary;
+    return {
+        model,
+        tier,
+        confidence: 0.85,
+        signals: ['pre-classified'],
+        savings: computeSavings(model),
+    };
+}
 // ─── Main Router ───
 export function routeRequest(prompt, profile = 'auto') {
     // Free profile — always use free model

package/package.json

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