@blockrun/franklin 3.8.25 → 3.8.27

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.
@@ -552,24 +553,58 @@ 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.
+        }
         // ── 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 +614,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,49 +745,29 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 sessionId,
             });
             // ── Router: resolve routing profiles to concrete models ──
+            // 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) {
-                if (groundingRetryCount > 0 && lastRoutedModel) {
-                    // Grounding retry re-enters the loop with a `[GROUNDING CHECK
-                    // FAILED]` user message that the router would classify as
-                    // SIMPLE on its own — which drops the turn onto a weak model
-                    // mid-task (observed in the CRCL log on 2026-04-22). Pin the
-                    // model the router picked on the first iteration so retries
-                    // stay on the same tier.
-                    resolvedModel = lastRoutedModel;
-                }
-                else {
-                    // Extract latest user text for classification
-                    const lastUser = [...history].reverse().find((m) => m.role === 'user');
-                    const userText = typeof lastUser?.content === 'string'
-                        ? lastUser.content
-                        : Array.isArray(lastUser?.content)
-                            ? lastUser.content
-                                .filter(p => p.type === 'text')
-                                .map(p => p.text ?? '')
-                                .join(' ')
-                            : '';
-                    const routing = await routeRequestAsync(userText, routingProfile);
-                    resolvedModel = routing.model;
-                    routingTier = routing.tier;
-                    routingConfidence = routing.confidence;
-                    routingSavings = routing.savings;
-                    lastRoutedModel = routing.model;
-                    lastRoutedCategory = routing.signals[0] || '';
-                    // Surface the routing decision so users know which concrete model
-                    // just got picked. Without this the status bar reads "auto" and
-                    // users have no idea what's actually running — or worse, they
-                    // believe they're stuck on the last-seen concrete name.
-                    if (loopCount === 1) {
-                        onEvent({
-                            kind: 'text_delta',
-                            text: `*Auto → ${routing.model}*\n\n`,
-                        });
-                    }
+                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] || '';
+                if (loopCount === 1) {
+                    onEvent({
+                        kind: 'text_delta',
+                        text: `*Auto → ${routing.model}*\n\n`,
+                    });
                 }
             }
             // Update token estimation model for more accurate byte-per-token ratio

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.25",
+  "version": "3.8.27",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {