@blockrun/franklin 3.15.93 → 3.15.95

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

@@ -1011,10 +1011,26 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // where input-replay tax has clearly started biting; the
             // fire-once-per-turn flag still bounds the worst case at one
             // extra summary call (~$0.005).
+            //
+            // 2026-05-11: added a high-cost early-exit. The original
+            // (>15 calls AND >$0.03) gate works well for cheap models
+            // where 15 calls clears the $0.03 floor trivially. For Opus-
+            // class models, cost climbs much faster than call count —
+            // verified in production from a real session:
+            // `Research-bloat compacted at 16 calls / $9.4552: ~3129
+            // tokens`. By the time the 16-call gate fired, $9.45 was
+            // already spent on input-replay. With an early-exit at
+            // $1.00 turn-cost, the compact would have fired around
+            // call 4-5, saving ~$8 on that turn. The cost cap is
+            // intentionally conservative — even extended-thinking Opus
+            // shouldn't legitimately need >$1 of context-replay before
+            // compacting (the compact itself runs on a cheaper model
+            // and costs <$0.05).
+            const TURN_COST_CAP_FOR_EARLY_COMPACT = 1.00;
             if (!bloatCompactedThisTurn &&
                 compactFailures < 3 &&
-                turnToolCalls > 15 &&
-                turnCostUsd > 0.03) {
+                ((turnToolCalls > 15 && turnCostUsd > 0.03) ||
+                    turnCostUsd > TURN_COST_CAP_FOR_EARLY_COMPACT)) {
                 try {
                     const beforeTokens = estimateHistoryTokens(history);
                     const { history: compacted, compacted: didCompact } = await forceCompact(history, config.model, client, config.debug);
@@ -1640,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/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.93",
+  "version": "3.15.95",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {