@blockrun/franklin 3.15.11 → 3.15.13

package/dist/agent/context.js

@@ -326,6 +326,12 @@ Your training data is frozen in the past. Live-world questions MUST be answered
 
 If you find yourself about to emit one of these, stop and call the tool instead. If you don't know which ticker the user means, call ExaSearch or AskUser — never deflect.
 
+**Trading verdicts (TradingSignal).** When the user asks "how does $TICKER look" / "should I buy X" / "is BTC overbought":
+- Run **TradingSignal** with default lookback (90d). Lower values leave MACD undefined.
+- The tool returns a **Verdict** section with \`Direction\`, \`Bull signals\`, \`Bear signals\`. Echo it directly. Do not soften "bullish" to "leaning slightly positive" — say what the data says.
+- If \`Data Notes\` lists an indicator as "insufficient data", state that explicitly to the user and suggest re-running with more days. Do NOT pretend that indicator is "neutral".
+- **Forbidden default**: "持有观望", "wait and see", "hold for clearer signals" — these are bugs when ≥2 indicators voted in a clear direction. Bail out to those phrases ONLY when (a) the Verdict says \`neutral\` AND (b) the bull/bear signal lists are both genuinely empty or one of each. Otherwise commit to a direction with the reasoning the tool already gave you.
+
 **Media generation (ImageGen / VideoGen).** Pass just the user's descriptive prompt and the output path — do NOT pass \`model\`. The harness picks the right model for the requested style + budget, refines loose prompts using a 5-slot template (scene / subject / details / use case / constraints), and surfaces both the refinement and a cost proposal through AskUser before spending. If the user wants their prompt left exactly as written, prefix it with \`///\` to skip refinement. Only pass \`model\` explicitly if the user named one specifically.`;
 }
 function getTokenEfficiencySection() {

package/dist/agent/loop.js

@@ -24,7 +24,7 @@ import { logger, setDebugMode } from '../logger.js';
 import { estimateCost, OPUS_PRICING } from '../pricing.js';
 import { maybeMidSessionExtract } from '../learnings/extractor.js';
 import { extractMentions, buildEntityContext, loadEntities } from '../brain/store.js';
-import { routeRequestAsync, resolveTierToModel, parseRoutingProfile, getFallbackChain } from '../router/index.js';
+import { routeRequestAsync, resolveTierToModel, parseRoutingProfile, getFallbackChain, pickFreeFallback } 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';
@@ -1098,8 +1098,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     if (lastRoutedCategory) {
                         recordOutcome(lastRoutedCategory, config.model, 'payment');
                     }
-                    const FREE_MODELS = ['nvidia/qwen3-coder-480b', 'nvidia/llama-4-maverick', 'nvidia/glm-4.7'];
-                    const nextFree = FREE_MODELS.find(m => !turnFailedModels.has(m));
+                    const nextFree = pickFreeFallback(lastRoutedCategory, turnFailedModels);
                     if (nextFree) {
                         const oldModel = config.model;
                         config.model = nextFree;
@@ -1120,8 +1119,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     if (lastRoutedCategory) {
                         recordOutcome(lastRoutedCategory, config.model, 'rate_limit');
                     }
-                    const FREE_MODELS = ['nvidia/qwen3-coder-480b', 'nvidia/llama-4-maverick', 'nvidia/glm-4.7'];
-                    const nextFree = FREE_MODELS.find(m => !turnFailedModels.has(m));
+                    const nextFree = pickFreeFallback(lastRoutedCategory, turnFailedModels);
                     if (nextFree) {
                         const oldModel = config.model;
                         config.model = nextFree;

package/dist/router/index.d.ts

@@ -49,6 +49,12 @@ export declare function routeRequest(prompt: string, profile?: RoutingProfile):
  * Get fallback models for a tier
  */
 export declare function getFallbackChain(tier: Tier, profile?: RoutingProfile): string[];
+/**
+ * Pick the next free model to try given the question category and which
+ * free models have already failed this turn. Returns undefined when every
+ * candidate has been exhausted (caller should surface an error to user).
+ */
+export declare function pickFreeFallback(category: string, alreadyFailed: Set<string>): string | undefined;
 /**
  * Parse routing profile from model string
  */

package/dist/router/index.js

@@ -483,10 +483,45 @@ function computeSavings(model) {
  */
 export function getFallbackChain(tier, profile = 'auto') {
     if (profile === 'free')
-        return ['nvidia/qwen3-coder-480b'];
+        return FREE_MODELS_BY_CATEGORY.chat;
     const config = AUTO_TIERS[tier];
     return [config.primary, ...config.fallback];
 }
+// ─── Free-tier fallback (used when paid models 402 / rate-limit) ───
+// Free fallback chains by question category. Used when a paid model fails
+// mid-turn (402 payment, rate-limit) and we need a zero-cost replacement
+// to keep the user moving without waiting for funding.
+//
+// The lists are ordered: best-fit free model first, then degraded fallbacks.
+// Coding goes to qwen3-coder; everything else (chat / trading / research /
+// reasoning / creative) prefers general-purpose free models that aren't
+// coder-tuned. Without this split, a BTC question that exhausted paid
+// models was being handed to qwen3-coder-480b — a coder model trying to
+// do technical analysis. Reported 2026-05-03 with a markets question
+// routed to a coder model on Sonnet failure.
+const FREE_MODELS_BY_CATEGORY = {
+    coding: ['nvidia/qwen3-coder-480b', 'nvidia/glm-4.7', 'nvidia/llama-4-maverick'],
+    trading: ['nvidia/glm-4.7', 'nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
+    research: ['nvidia/glm-4.7', 'nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
+    reasoning: ['nvidia/glm-4.7', 'nvidia/qwen3-coder-480b', 'nvidia/llama-4-maverick'],
+    chat: ['nvidia/llama-4-maverick', 'nvidia/glm-4.7', 'nvidia/qwen3-coder-480b'],
+    creative: ['nvidia/llama-4-maverick', 'nvidia/glm-4.7', 'nvidia/qwen3-coder-480b'],
+};
+const DEFAULT_FREE_CHAIN = [
+    'nvidia/glm-4.7',
+    'nvidia/llama-4-maverick',
+    'nvidia/qwen3-coder-480b',
+];
+/**
+ * Pick the next free model to try given the question category and which
+ * free models have already failed this turn. Returns undefined when every
+ * candidate has been exhausted (caller should surface an error to user).
+ */
+export function pickFreeFallback(category, alreadyFailed) {
+    const chain = FREE_MODELS_BY_CATEGORY[category]
+        ?? DEFAULT_FREE_CHAIN;
+    return chain.find(m => !alreadyFailed.has(m));
+}
 /**
  * Parse routing profile from model string
  */

package/dist/tools/trading.js

@@ -16,8 +16,19 @@ function formatUsd(n) {
         return `$${(n / 1e3).toFixed(1)}K`;
     return `$${n.toFixed(2)}`;
 }
+// MACD needs slow EMA (26) + signal EMA (9) = 35 closes minimum for the
+// signal/histogram to be defined. Default was 30, which left signal=NaN
+// and trend stuck at 'neutral' on every call — see the 2026-05-03 BTC
+// report where the agent had to write "MACD signal can't be computed
+// due to insufficient data". 90d gives stable MACD plus enough room for
+// reasonable Bollinger bandwidth and annualized volatility readings.
+const DEFAULT_LOOKBACK_DAYS = 90;
+const MIN_DAYS_FOR_MACD = 35;
+function fmtNumber(n, digits) {
+    return Number.isFinite(n) ? n.toFixed(digits) : 'n/a';
+}
 async function executeSignal(input, _ctx) {
-    const { ticker, days = 30 } = input;
+    const { ticker, days = DEFAULT_LOOKBACK_DAYS } = input;
     if (!ticker) {
         return { output: 'Error: ticker is required', isError: true };
     }
@@ -37,23 +48,45 @@ async function executeSignal(input, _ctx) {
     const macdResult = macd(closes);
     const bbResult = bollingerBands(closes);
     const volResult = volatility(closes);
-    // Determine overall direction from indicators
+    // Per-indicator validity. Each has its own minimum sample requirement
+    // and we surface the gap rather than silently defaulting to 'neutral'.
+    const macdValid = Number.isFinite(macdResult.signal) && Number.isFinite(macdResult.histogram);
+    const dataNotes = [];
+    if (!macdValid) {
+        dataNotes.push(`MACD signal/histogram unavailable — need ≥${MIN_DAYS_FOR_MACD} closes, got ${closes.length}. ` +
+            `Re-run with days=${MIN_DAYS_FOR_MACD} or higher for full trend detection.`);
+    }
+    // Direction count — only valid indicators contribute. A NaN MACD must
+    // not be counted as a 'neutral' vote, otherwise the agent reads weak
+    // data as a reason to recommend "wait and see".
     let bullish = 0;
     let bearish = 0;
-    if (rsiResult.interpretation === 'oversold')
-        bullish++;
-    if (rsiResult.interpretation === 'overbought')
-        bearish++;
-    if (macdResult.trend === 'bullish')
-        bullish++;
-    if (macdResult.trend === 'bearish')
-        bearish++;
-    if (bbResult.position === 'below')
-        bullish++;
-    if (bbResult.position === 'above')
-        bearish++;
+    let votingIndicators = 0;
+    if (Number.isFinite(rsiResult.value)) {
+        votingIndicators++;
+        if (rsiResult.interpretation === 'oversold')
+            bullish++;
+        if (rsiResult.interpretation === 'overbought')
+            bearish++;
+    }
+    if (macdValid) {
+        votingIndicators++;
+        if (macdResult.trend === 'bullish')
+            bullish++;
+        if (macdResult.trend === 'bearish')
+            bearish++;
+    }
+    if (Number.isFinite(bbResult.middle)) {
+        votingIndicators++;
+        if (bbResult.position === 'below')
+            bullish++;
+        if (bbResult.position === 'above')
+            bearish++;
+    }
     const direction = bullish > bearish ? 'bullish' : bearish > bullish ? 'bearish' : 'neutral';
-    const confidence = Math.max(bullish, bearish) / 3;
+    const confidence = votingIndicators > 0
+        ? Math.max(bullish, bearish) / votingIndicators
+        : 0;
     bus.emit(makeEvent({
         type: 'signal.detected',
         source: 'trading',
@@ -71,6 +104,28 @@ async function executeSignal(input, _ctx) {
     }));
     const { price, change24h, marketCap, volume24h } = priceResult;
     const last5 = closes.slice(-5).map(c => c.toFixed(2)).join(', ');
+    // MACD line: when signal/histogram are NaN, say so explicitly instead
+    // of rendering "1822.7300 / Signal: NaN / Histogram: NaN — neutral",
+    // which read as a real signal to translation models.
+    const macdLine = macdValid
+        ? `- **MACD:** ${fmtNumber(macdResult.macd, 4)} / Signal: ${fmtNumber(macdResult.signal, 4)} / Histogram: ${fmtNumber(macdResult.histogram, 4)} — ${macdResult.trend}`
+        : `- **MACD:** ${fmtNumber(macdResult.macd, 4)} / Signal: insufficient data / Histogram: insufficient data — *not enough closes for trend*`;
+    // Bull / bear breakdown so the agent can echo a real verdict instead
+    // of falling back to "wait and see".
+    const bullSignals = [];
+    const bearSignals = [];
+    if (rsiResult.interpretation === 'oversold')
+        bullSignals.push('RSI oversold');
+    if (rsiResult.interpretation === 'overbought')
+        bearSignals.push('RSI overbought');
+    if (macdValid && macdResult.trend === 'bullish')
+        bullSignals.push('MACD trending up');
+    if (macdValid && macdResult.trend === 'bearish')
+        bearSignals.push('MACD trending down');
+    if (Number.isFinite(bbResult.middle) && bbResult.position === 'below')
+        bullSignals.push('price below lower Bollinger');
+    if (Number.isFinite(bbResult.middle) && bbResult.position === 'above')
+        bearSignals.push('price above upper Bollinger');
     const output = [
         `## ${upper} Signal Report`,
         '',
@@ -78,11 +133,17 @@ async function executeSignal(input, _ctx) {
         `**Market Cap:** ${formatUsd(marketCap)}`,
         `**24h Volume:** ${formatUsd(volume24h)}`,
         '',
-        `### Technical Indicators (${days}d lookback)`,
-        `- **RSI(14):** ${rsiResult.value.toFixed(1)} — ${rsiResult.interpretation}`,
-        `- **MACD:** ${macdResult.macd.toFixed(4)} / Signal: ${macdResult.signal.toFixed(4)} / Histogram: ${macdResult.histogram.toFixed(4)} — ${macdResult.trend}`,
-        `- **Bollinger:** Upper ${bbResult.upper.toFixed(2)} / Middle ${bbResult.middle.toFixed(2)} / Lower ${bbResult.lower.toFixed(2)} — Price ${bbResult.position}`,
-        `- **Volatility:** ${(volResult.annualized * 100).toFixed(1)}% annualized — ${volResult.interpretation}`,
+        `### Technical Indicators (${days}d lookback, ${closes.length} closes)`,
+        `- **RSI(14):** ${fmtNumber(rsiResult.value, 1)} — ${rsiResult.interpretation}`,
+        macdLine,
+        `- **Bollinger:** Upper ${fmtNumber(bbResult.upper, 2)} / Middle ${fmtNumber(bbResult.middle, 2)} / Lower ${fmtNumber(bbResult.lower, 2)} — Price ${bbResult.position}`,
+        `- **Volatility:** ${fmtNumber(volResult.annualized * 100, 1)}% annualized — ${volResult.interpretation}`,
+        '',
+        `### Verdict`,
+        `**Direction:** ${direction} (${votingIndicators} indicator${votingIndicators === 1 ? '' : 's'} voting, confidence ${(confidence * 100).toFixed(0)}%)`,
+        bullSignals.length > 0 ? `**Bull signals:** ${bullSignals.join(', ')}` : '**Bull signals:** none',
+        bearSignals.length > 0 ? `**Bear signals:** ${bearSignals.join(', ')}` : '**Bear signals:** none',
+        ...(dataNotes.length > 0 ? ['', `### Data Notes`, ...dataNotes.map(n => `- ${n}`)] : []),
         '',
         `### Raw Data`,
         `Closes (last 5): ${last5}`,
@@ -92,12 +153,12 @@ async function executeSignal(input, _ctx) {
 export const tradingSignalCapability = {
     spec: {
         name: 'TradingSignal',
-        description: 'Get current price, technical indicators (RSI, MACD, Bollinger Bands, volatility), and a signal summary for a cryptocurrency. Returns raw data for the agent to analyze and interpret.',
+        description: 'Get current price, technical indicators (RSI, MACD, Bollinger Bands, volatility), and a verdict (bullish / bearish / neutral with confidence) for a cryptocurrency. Always returns a Verdict section with bull/bear signal lists — echo it directly. When MACD signal/histogram report "insufficient data", say so explicitly; do NOT default to "wait and see".',
         input_schema: {
             type: 'object',
             properties: {
                 ticker: { type: 'string', description: 'Cryptocurrency ticker, e.g. "BTC", "ETH"' },
-                days: { type: 'number', description: 'Lookback period for indicators. Default: 30' },
+                days: { type: 'number', description: 'Lookback period in days. Default 90 (recommended). Below 35 will leave MACD signal/histogram undefined.' },
             },
             required: ['ticker'],
         },

package/package.json

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