@blockrun/franklin 3.15.77 → 3.15.79

package/dist/agent/loop.js

@@ -177,6 +177,32 @@ function sanitizeHistory(history) {
  * Detect media-related errors (image too large, too many images, PDF too large).
  * These can be recovered by stripping media blocks and retrying.
  */
+/**
+ * True when the assistant's last emitted text segment ends with a question
+ * mark (ASCII `?` or fullwidth `？`). Used to render an end-of-turn marker
+ * so users don't read the post-question silence as "Franklin died." Trim
+ * trailing whitespace + closing punctuation that doesn't change intent
+ * (newlines, single closing quote/paren) before checking.
+ */
+function endedWithQuestion(parts) {
+    if (!parts || parts.length === 0)
+        return false;
+    // Walk back to the last text segment. Skip thinking/tool_use parts.
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const p = parts[i];
+        if (p.type !== 'text')
+            continue;
+        const text = p.text;
+        if (typeof text !== 'string')
+            return false;
+        // Strip trailing whitespace + the ~3 closing chars that commonly
+        // follow a question without changing it (")", "'", "\"", "*", ")",
+        // "*", whitespace).
+        const trimmed = text.replace(/[\s)\]'"*`)]+$/u, '');
+        return /[?？]$/.test(trimmed);
+    }
+    return false;
+}
 function isMediaSizeError(msg) {
     return ((msg.includes('image exceeds') && msg.includes('maximum')) ||
         (msg.includes('image dimensions exceed')) ||
@@ -1737,6 +1763,17 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 if (lastRoutedCategory && lastRoutedModel) {
                     recordOutcome(lastRoutedCategory, lastRoutedModel, 'continued', turnToolCalls);
                 }
+                // End-of-turn marker for question-shaped responses. Real-world UX
+                // problem 2026-05-06: agent finishes a turn with "要我查一下 X 吗?"
+                // and stops; the user reads the silence as "Franklin died" twice in
+                // one hour. The Ink input box is already on screen but it's easy to
+                // miss after a long output scroll. A single trailing italic line
+                // makes the wait state explicit. Only fires when the model's last
+                // emitted text ends with `?` or `？` so non-question turns don't
+                // get a noisy hint.
+                if (endedWithQuestion(responseParts)) {
+                    onEvent({ kind: 'text_delta', text: '\n*▸ awaiting your reply (or type a new message)*\n' });
+                }
                 onEvent({ kind: 'turn_done', reason: 'completed' });
                 break;
             }

package/dist/commands/stats.js

@@ -4,6 +4,7 @@
  */
 import chalk from 'chalk';
 import { clearStats, getStatsSummary } from '../stats/tracker.js';
+import { summarizeSdkSettlements } from '../stats/cost-log.js';
 export function statsCommand(options) {
     if (options.clear) {
         clearStats();
@@ -11,6 +12,27 @@ export function statsCommand(options) {
         return;
     }
     const { stats, opusCost, saved, savedPct, avgCostPerRequest, period } = getStatsSummary();
+    // SDK ledger reconciliation. `franklin-stats.json` only captures requests
+    // that flowed through Franklin's `recordUsage()` paths (main agent loop +
+    // proxy). Helper LLM calls and SDK-internal probes settle x402 payments
+    // through `~/.blockrun/cost_log.jsonl` (SDK-owned) — adding it here so
+    // the user sees the wire-level total alongside Franklin's recorded one.
+    // The gap between the two = recording instrumentation that's still
+    // missing from helper paths (analyzeTurn, compaction, evaluator, etc.).
+    const sdkLedger = summarizeSdkSettlements();
+    const recordedTotal = stats.totalCostUsd;
+    const sdkTotal = sdkLedger.totalUsd;
+    const gap = sdkTotal - recordedTotal;
+    const gapPct = sdkTotal > 0 ? (gap / sdkTotal) * 100 : 0;
+    // Bidirectional check. Two distinct gap meanings:
+    //   sdkTotal > recordedTotal → helper LLM calls / SDK probes settled
+    //     on-chain but bypassed Franklin's recordUsage. The ledger is the
+    //     wire truth; recorded total is incomplete.
+    //   sdkTotal < recordedTotal → cost_log.jsonl was probably rotated /
+    //     truncated since the stats started accumulating. Recorded total is
+    //     more complete; the ledger is just the recent slice.
+    // Treat any gap > $0.01 OR > 5% (in either direction) as worth flagging.
+    const significantGap = sdkTotal > 0 && (Math.abs(gap) > 0.01 || Math.abs(gapPct) > 5);
     // JSON output for programmatic access
     if (options.json) {
         console.log(JSON.stringify({
@@ -22,6 +44,21 @@ export function statsCommand(options) {
                 avgCostPerRequest,
                 period,
             },
+            sdkLedger: {
+                path: sdkLedger.path,
+                entries: sdkLedger.count,
+                totalUsd: sdkTotal,
+                byEndpoint: sdkLedger.byEndpoint.slice(0, 10),
+                firstTs: sdkLedger.firstTs,
+                lastTs: sdkLedger.lastTs,
+            },
+            reconciliation: {
+                recordedUsd: recordedTotal,
+                sdkLedgerUsd: sdkTotal,
+                gapUsd: gap,
+                gapPct,
+                significantGap,
+            },
         }, null, 2));
         return;
     }
@@ -36,7 +73,22 @@ export function statsCommand(options) {
     // Overview
     console.log(chalk.bold('\n  Overview') + chalk.gray(` (${period})\n`));
     console.log(`    Requests:       ${chalk.cyan(stats.totalRequests.toLocaleString())}`);
-    console.log(`    Total Cost:     ${chalk.green('$' + stats.totalCostUsd.toFixed(4))}`);
+    console.log(`    Recorded Cost:  ${chalk.green('$' + stats.totalCostUsd.toFixed(4))}` +
+        chalk.gray('  (franklin-stats.json — main loop + proxy + tools that call recordUsage)'));
+    if (sdkTotal > 0) {
+        const ledgerColor = significantGap ? chalk.yellow : chalk.green;
+        console.log(`    SDK Ledger:     ${ledgerColor('$' + sdkTotal.toFixed(4))}` +
+            chalk.gray(`  (cost_log.jsonl — actual x402 settlements, ${sdkLedger.count} rows)`));
+        if (significantGap) {
+            const explanation = gap > 0
+                ? 'helper LLM calls (analyzeTurn / compaction / evaluator / verification / subagent / MoA / etc.) settled on-chain but bypassed recordUsage. SDK ledger is the wire truth.'
+                : 'cost_log.jsonl looks rotated or truncated — it covers fewer rows than franklin-stats.json. Recorded total is more complete than the ledger here.';
+            console.log(chalk.yellow(`    ⚠ Gap:          $${Math.abs(gap).toFixed(4)} (${Math.abs(gapPct).toFixed(1)}%) ${gap > 0 ? '↑' : '↓'} — ${explanation}`));
+        }
+        else {
+            console.log(chalk.gray(`    Gap:            $${gap.toFixed(4)} (${gapPct.toFixed(1)}%)`));
+        }
+    }
     console.log(`    Avg per Request: ${chalk.gray('$' + avgCostPerRequest.toFixed(6))}`);
     console.log(`    Input Tokens:   ${stats.totalInputTokens.toLocaleString()}`);
     console.log(`    Output Tokens:  ${stats.totalOutputTokens.toLocaleString()}`);
@@ -75,6 +127,18 @@ export function statsCommand(options) {
     else {
         console.log(chalk.gray('    Not enough data to calculate savings'));
     }
+    // SDK ledger breakdown — surfaces non-chat endpoints (Modal, PM, x.com,
+    // exa, etc.) that flow through tools and may not show up in byModel.
+    // Only print when the ledger has real data.
+    if (sdkLedger.count > 0 && sdkLedger.byEndpoint.length > 0) {
+        console.log(chalk.bold('\n  SDK Ledger (top endpoints)\n'));
+        for (const e of sdkLedger.byEndpoint.slice(0, 6)) {
+            const pct = sdkTotal > 0 ? ((e.costUsd / sdkTotal) * 100).toFixed(1) : '0';
+            const display = e.endpoint.length > 40 ? e.endpoint.slice(0, 37) + '...' : e.endpoint;
+            console.log(`    ${chalk.cyan(display)}`);
+            console.log(chalk.gray(`      ${e.count} call${e.count === 1 ? '' : 's'} · $${e.costUsd.toFixed(4)} (${pct}%)`));
+        }
+    }
     // Recent activity (last 5 requests)
     if (stats.history.length > 0) {
         console.log(chalk.bold('\n  Recent Activity\n'));

package/dist/stats/cost-log.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Reader for `~/.blockrun/cost_log.jsonl` — the SDK-owned ledger of every
+ * settled x402 payment.
+ *
+ * Franklin's own `franklin-stats.json` and `franklin-audit.jsonl` only
+ * capture calls that pass through specific code paths (the main agent
+ * loop and the proxy). Helper LLM calls (analyzeTurn, prefetchForIntent,
+ * compaction, evaluator, verification, MoA, subagent, learning extraction,
+ * etc.) all settle x402 payments through the SDK — those payments DO get
+ * recorded in cost_log.jsonl by `@blockrun/llm` itself, but Franklin's
+ * stats infra had been ignoring this file entirely.
+ *
+ * Verified 2026-05-06 against a real machine: cost_log.jsonl is written
+ * by the SDK with snake_case keys (`cost_usd`, `ts` in unix seconds with
+ * subsecond precision — Python convention) and Franklin's reads/writes
+ * use camelCase + ms. This module bridges the format gap so stats /
+ * insights / `franklin balance` can surface the wallet-truth total
+ * alongside the recorded total.
+ *
+ * Responsibility: read-only. We never write or trim cost_log.jsonl —
+ * the SDK owns it.
+ */
+export interface SettlementRow {
+    /** Endpoint path that was paid for, e.g. `/v1/chat/completions`. */
+    endpoint: string;
+    /** USD settled on-chain via x402. */
+    costUsd: number;
+    /** Unix milliseconds (normalized — SDK writes seconds). */
+    ts: number;
+}
+export interface SettlementSummary {
+    /** Path to cost_log.jsonl (or the fallback location). */
+    path: string;
+    /** Total entries read. */
+    count: number;
+    /** Sum of `costUsd` across all rows in window. */
+    totalUsd: number;
+    /** Per-endpoint breakdown sorted by cost descending. */
+    byEndpoint: Array<{
+        endpoint: string;
+        count: number;
+        costUsd: number;
+    }>;
+    /** First and last timestamps observed in the window (unix ms), or null. */
+    firstTs: number | null;
+    lastTs: number | null;
+}
+interface ReadOptions {
+    /** Override the cost_log path (for tests). Defaults to ~/.blockrun/cost_log.jsonl. */
+    path?: string;
+    sinceMs?: number;
+    untilMs?: number;
+}
+/**
+ * Load + parse cost_log.jsonl. Optional time window in unix milliseconds.
+ * Skips malformed lines silently (the SDK's JSONL writer is well-behaved
+ * but we don't want a single corrupted line to nuke the whole readout).
+ *
+ * Returns an empty list if the file doesn't exist — callers should treat
+ * that as "no SDK ledger available" rather than an error, since the file
+ * is only created on the first paid call.
+ */
+export declare function loadSdkSettlements(opts?: ReadOptions): SettlementRow[];
+/** Aggregate the SDK ledger into a single summary object. */
+export declare function summarizeSdkSettlements(opts?: ReadOptions): SettlementSummary;
+export {};

package/dist/stats/cost-log.js

@@ -0,0 +1,111 @@
+/**
+ * Reader for `~/.blockrun/cost_log.jsonl` — the SDK-owned ledger of every
+ * settled x402 payment.
+ *
+ * Franklin's own `franklin-stats.json` and `franklin-audit.jsonl` only
+ * capture calls that pass through specific code paths (the main agent
+ * loop and the proxy). Helper LLM calls (analyzeTurn, prefetchForIntent,
+ * compaction, evaluator, verification, MoA, subagent, learning extraction,
+ * etc.) all settle x402 payments through the SDK — those payments DO get
+ * recorded in cost_log.jsonl by `@blockrun/llm` itself, but Franklin's
+ * stats infra had been ignoring this file entirely.
+ *
+ * Verified 2026-05-06 against a real machine: cost_log.jsonl is written
+ * by the SDK with snake_case keys (`cost_usd`, `ts` in unix seconds with
+ * subsecond precision — Python convention) and Franklin's reads/writes
+ * use camelCase + ms. This module bridges the format gap so stats /
+ * insights / `franklin balance` can surface the wallet-truth total
+ * alongside the recorded total.
+ *
+ * Responsibility: read-only. We never write or trim cost_log.jsonl —
+ * the SDK owns it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+function getCostLogPath() {
+    return path.join(BLOCKRUN_DIR, 'cost_log.jsonl');
+}
+/**
+ * Load + parse cost_log.jsonl. Optional time window in unix milliseconds.
+ * Skips malformed lines silently (the SDK's JSONL writer is well-behaved
+ * but we don't want a single corrupted line to nuke the whole readout).
+ *
+ * Returns an empty list if the file doesn't exist — callers should treat
+ * that as "no SDK ledger available" rather than an error, since the file
+ * is only created on the first paid call.
+ */
+export function loadSdkSettlements(opts) {
+    const file = opts?.path ?? getCostLogPath();
+    if (!fs.existsSync(file))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    const sinceMs = opts?.sinceMs ?? 0;
+    const untilMs = opts?.untilMs ?? Number.POSITIVE_INFINITY;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const endpoint = typeof obj.endpoint === 'string' ? obj.endpoint : '';
+        if (!endpoint)
+            continue;
+        // SDK writes `cost_usd`. Defensively also accept `costUsd` in case a
+        // future SDK release switches conventions.
+        const costRaw = obj.cost_usd ?? obj.costUsd;
+        const costUsd = typeof costRaw === 'number' && Number.isFinite(costRaw) ? costRaw : 0;
+        // SDK writes `ts` as unix SECONDS with subsecond precision (1773424791.43...).
+        // Normalize to ms so callers can compare against `Date.now()` directly.
+        const tsRaw = obj.ts;
+        if (typeof tsRaw !== 'number' || !Number.isFinite(tsRaw))
+            continue;
+        const ts = tsRaw < 1e12 ? Math.round(tsRaw * 1000) : Math.round(tsRaw);
+        if (ts < sinceMs || ts > untilMs)
+            continue;
+        rows.push({ endpoint, costUsd, ts });
+    }
+    return rows;
+}
+/** Aggregate the SDK ledger into a single summary object. */
+export function summarizeSdkSettlements(opts) {
+    const rows = loadSdkSettlements(opts);
+    let totalUsd = 0;
+    let firstTs = null;
+    let lastTs = null;
+    const byEndpointMap = new Map();
+    for (const r of rows) {
+        totalUsd += r.costUsd;
+        if (firstTs === null || r.ts < firstTs)
+            firstTs = r.ts;
+        if (lastTs === null || r.ts > lastTs)
+            lastTs = r.ts;
+        const acc = byEndpointMap.get(r.endpoint) ?? { count: 0, costUsd: 0 };
+        acc.count += 1;
+        acc.costUsd += r.costUsd;
+        byEndpointMap.set(r.endpoint, acc);
+    }
+    const byEndpoint = Array.from(byEndpointMap.entries())
+        .map(([endpoint, v]) => ({ endpoint, count: v.count, costUsd: v.costUsd }))
+        .sort((a, b) => b.costUsd - a.costUsd);
+    return {
+        path: opts?.path ?? getCostLogPath(),
+        count: rows.length,
+        totalUsd,
+        byEndpoint,
+        firstTs,
+        lastTs,
+    };
+}

package/dist/tools/trading.js

@@ -16,6 +16,38 @@ function formatUsd(n) {
         return `$${(n / 1e3).toFixed(1)}K`;
     return `$${n.toFixed(2)}`;
 }
+/**
+ * US-listed equity tickers that ALSO have meaningful tokenized listings on-chain.
+ * When TradingSignal is called with one of these, the crypto-leg data we return
+ * is the tokenized variant — not the spot equity. We surface a notice in the
+ * output so the agent knows to also pull TradingMarket stockPrice market='us'
+ * for the equity side, and can compute the basis spread (premium/discount of
+ * tokenized vs spot — that spread is real alpha for some flows).
+ *
+ * Conservative list: high-liquidity US equities that have shown up as actively
+ * traded tokenized variants. Add more as they materialize. Verified 2026-05-06
+ * via a real session where the agent asked TradingSignal for CRCL, got the
+ * tokenized $0-cap leg back, and correctly recovered to "ignore this, pull
+ * Pyth" — but the user lost an extra $0.005 + a confused turn before recovery.
+ */
+const KNOWN_DUAL_LISTED_EQUITIES = new Set([
+    'CRCL', // Circle Internet Group
+    'COIN', // Coinbase
+    'MSTR', // Strategy (formerly MicroStrategy)
+    'PLTR', // Palantir
+    'TSLA', // Tesla
+    'AAPL', // Apple
+    'NVDA', // NVIDIA
+    'MSFT', // Microsoft
+    'AMZN', // Amazon
+    'GOOGL', // Alphabet
+    'META', // Meta
+    'JPM', // JPMorgan Chase
+    'BRK', // Berkshire Hathaway (BRK.A / BRK.B)
+    'HOOD', // Robinhood
+    'SQ', // Block
+    'PYPL', // PayPal
+]);
 // 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
@@ -126,9 +158,17 @@ async function executeSignal(input, _ctx) {
         bullSignals.push('price below lower Bollinger');
     if (Number.isFinite(bbResult.middle) && bbResult.position === 'above')
         bearSignals.push('price above upper Bollinger');
+    // Dual-listing notice: prepend before the body when the ticker is also a
+    // known US equity. Doesn't suppress the crypto/tokenized data — that data
+    // is its own legitimate signal — just labels it correctly so the agent
+    // knows to also fetch the spot equity for the basis spread.
+    const dualListingNote = KNOWN_DUAL_LISTED_EQUITIES.has(upper)
+        ? `> ⚠ \`${upper}\` is also a US-listed equity. The data below is the **crypto / tokenized leg** (CoinGecko). For the spot equity (NYSE / NASDAQ) call \`TradingMarket\` with \`action: stockPrice, market: "us"\`. Run both in parallel to compute the basis spread (premium/discount of tokenized vs spot — that spread is the signal).\n`
+        : '';
     const output = [
         `## ${upper} Signal Report`,
         '',
+        ...(dualListingNote ? [dualListingNote] : []),
         `**Price:** $${price.toLocaleString()} USD (${change24h > 0 ? '+' : ''}${change24h.toFixed(2)}% 24h)`,
         `**Market Cap:** ${formatUsd(marketCap)}`,
         `**24h Volume:** ${formatUsd(volume24h)}`,
@@ -153,7 +193,7 @@ async function executeSignal(input, _ctx) {
 export const tradingSignalCapability = {
     spec: {
         name: 'TradingSignal',
-        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".',
+        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". For tickers that ALSO trade as US equities (CRCL, COIN, MSTR, TSLA, AAPL, NVDA, etc.) the response includes a dual-listing note: TradingSignal returns the tokenized/crypto leg, and you should fire TradingMarket stockPrice market="us" in parallel to also get the spot equity. The basis spread between the two is itself the signal.',
         input_schema: {
             type: 'object',
             properties: {

package/package.json

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