@blockrun/franklin 3.15.78 → 3.15.79

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.78",
+  "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": {