@blockrun/franklin 3.15.94 → 3.15.96

package/dist/agent/llm.d.ts

@@ -46,6 +46,19 @@ export interface StreamChunk {
 export interface CompletionUsage {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Anthropic prompt-cache fields. `input_tokens` only counts the base
+     * (uncached) portion; the cache-creation and cache-read counts are
+     * separate and billed at different rates (1.25× / 0.1× of base input,
+     * respectively). Pre-fix, Franklin only read `input_tokens` and
+     * silently undercounted every vision / cache-using call's total
+     * token spend — verified 2026-05-11 from an Opus 4.7 turn billed
+     * $0.567 with audit logging `inputTokens: 3653` (implies ~113K real
+     * billed input tokens). Surface all three so audits, stats, and any
+     * future estimation paths see the full picture.
+     */
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
 }
 export interface LLMClientOptions {
     apiUrl: string;

package/dist/agent/llm.js

@@ -864,6 +864,15 @@ export class ModelClient {
                     const msgUsage = chunk.payload['usage'];
                     if (msgUsage) {
                         usage.outputTokens = msgUsage['output_tokens'] ?? usage.outputTokens;
+                        // Cache and tool-call breakdowns can arrive in message_delta
+                        // too; merge whatever's present without clobbering values set
+                        // by message_start.
+                        if (msgUsage['cache_creation_input_tokens'] !== undefined) {
+                            usage.cacheCreationInputTokens = msgUsage['cache_creation_input_tokens'];
+                        }
+                        if (msgUsage['cache_read_input_tokens'] !== undefined) {
+                            usage.cacheReadInputTokens = msgUsage['cache_read_input_tokens'];
+                        }
                     }
                     const delta = chunk.payload['delta'];
                     if (delta?.['stop_reason']) {
@@ -877,6 +886,18 @@ export class ModelClient {
                     if (msgUsage) {
                         usage.inputTokens = msgUsage['input_tokens'] ?? 0;
                         usage.outputTokens = msgUsage['output_tokens'] ?? 0;
+                        // Vision and prompt-cache calls return up to two extra
+                        // billed-tokens counts that input_tokens does NOT include:
+                        // cache_creation_input_tokens (1.25× base price) and
+                        // cache_read_input_tokens (0.1× base price). Without these,
+                        // any audit/stats over a vision-heavy session looks wildly
+                        // inconsistent with the wallet charge.
+                        if (msgUsage['cache_creation_input_tokens'] !== undefined) {
+                            usage.cacheCreationInputTokens = msgUsage['cache_creation_input_tokens'];
+                        }
+                        if (msgUsage['cache_read_input_tokens'] !== undefined) {
+                            usage.cacheReadInputTokens = msgUsage['cache_read_input_tokens'];
+                        }
                     }
                     break;
                 }

package/dist/agent/loop.js

@@ -1656,6 +1656,8 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 model: resolvedModel,
                 inputTokens,
                 outputTokens: usage.outputTokens,
+                cacheCreationInputTokens: usage.cacheCreationInputTokens,
+                cacheReadInputTokens: usage.cacheReadInputTokens,
                 costUsd: callCost,
                 // Any failed model this turn means the model that finally
                 // succeeded was a fallback. Without this, audit log read 0%

package/dist/commands/doctor.js

@@ -108,13 +108,27 @@ async function runChecks() {
                 status: 'ok',
                 detail: `${walletAddress.slice(0, 10)}…${walletAddress.slice(-6)}`,
             });
+            // Tiered balance status. Binary `> 0` was misleading — verified
+            // 2026-05-11 from a real run: doctor printed `✓ USDC balance
+            // $0.37` (green) on a wallet that couldn't fund a single Opus
+            // call ($0.50+ each). Threshold of $1.00 covers ~10 cheap-model
+            // calls or ~2 mid-tier calls — anything below that is
+            // operationally empty for paid workflows. Free models still work.
+            const LOW_BALANCE_THRESHOLD = 1.00;
+            const balanceStatus = walletBalance >= LOW_BALANCE_THRESHOLD ? 'ok' : 'warn';
+            const balanceDetail = walletBalance === 0
+                ? '$0.00 — free-tier models only (no paid calls possible)'
+                : walletBalance < LOW_BALANCE_THRESHOLD
+                    ? `$${walletBalance.toFixed(2)} — low; paid calls likely to fail mid-stream`
+                    : `$${walletBalance.toFixed(2)}`;
+            const balanceRemedy = walletBalance < LOW_BALANCE_THRESHOLD
+                ? `Send USDC on ${chain} to ${walletAddress} (or open http://localhost:3100/#wallet)`
+                : undefined;
             out.push({
                 name: 'USDC balance',
-                status: walletBalance > 0 ? 'ok' : 'warn',
-                detail: `$${walletBalance.toFixed(2)}${walletBalance === 0 ? ' — free-tier models only' : ''}`,
-                remedy: walletBalance === 0
-                    ? `Send USDC on ${chain} to ${walletAddress} to unlock paid models`
-                    : undefined,
+                status: balanceStatus,
+                detail: balanceDetail,
+                remedy: balanceRemedy,
             });
         }
         catch (err) {

package/dist/stats/audit.d.ts

@@ -14,6 +14,18 @@ export interface AuditEntry {
     model: string;
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Anthropic prompt-cache fields, captured when the model reports them
+     * in `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens`.
+     * `inputTokens` above is the *uncached* portion; the cache fields are
+     * additional billed input the gateway charges for separately. Without
+     * these, vision and cache-heavy sessions show a wildly inconsistent
+     * cost-per-token ratio in audit dashboards — verified 2026-05-11 from
+     * an Opus 4.7 call with inputTokens=3653 but costUsd=$0.567 (implies
+     * ~113K real billed tokens once cache_creation is counted).
+     */
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
     costUsd: number;
     latencyMs?: number;
     fallback?: boolean;

package/package.json

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