@blockrun/franklin 3.15.97 → 3.15.99

package/README.md

@@ -2,14 +2,15 @@
 
 <br>
 
-<img src="assets/terminal-banner.png" alt="Franklin terminal" width="680">
+<img src="assets/terminal-banner.png" alt="Franklin Agent terminal" width="680">
 
 <br><br>
 
+<h1>Franklin Agent</h1>
 <h3>The AI agent with a wallet.</h3>
 
 <p>
-  Other agents write code. Franklin writes code <em>and spends money</em> to get things done.<br>
+  Other agents write code. Franklin Agent writes code <em>and spends money</em> to get things done.<br>
   One wallet. Every model. Every paid API. Pay only for outcomes — not subscriptions.
 </p>
 
@@ -41,14 +42,14 @@
 
 ## The pitch in one paragraph
 
-Most coding agents write code. Franklin writes code **and spends money to get the job done**. It holds a USDC wallet, picks the best model per task from 55+ providers, purchases trading data, generates images, pays for web search — all autonomously. You state an outcome and set a budget. Franklin decides what to call, what to pay for, and when to stop. Every paid action routes through the [x402](https://x402.org) micropayment protocol and settles against your own wallet. No subscriptions. No API keys. No account. The wallet is the identity.
+Most coding agents write code. Franklin Agent writes code **and spends money to get the job done**. It holds a USDC wallet, picks the best model per task from 55+ providers, purchases trading data, generates images, pays for web search — all autonomously. You state an outcome and set a budget. Franklin Agent decides what to call, what to pay for, and when to stop. Every paid action routes through the [x402](https://x402.org) micropayment protocol and settles against your own wallet. No subscriptions. No API keys. No account. The wallet is the identity.
 
 Built by the [BlockRun](https://blockrun.ai) team. Apache-2.0. TypeScript. Ships as one npm package.
 
 > **YOPO — You Only Pay Outcome**
 >
 > Not a subscription (pay for access). Not a generic pay-per-call (pay for trying).
-> You pay only for the work Franklin delivers. Provider cost + 5%, settled per action
+> You pay only for the work Franklin Agent delivers. Provider cost + 5%, settled per action
 > in USDC. No monthly fees. No rate limits. No overdraft.
 
 ---
@@ -87,13 +88,13 @@ Free models work immediately. Paid models, image gen, and video gen activate the
 
 ## YOPO
 
-**You Only Pay Outcome.** This is Franklin's pricing model, and it is the opposite of almost every other AI product you use.
+**You Only Pay Outcome.** This is Franklin Agent's pricing model, and it is the opposite of almost every other AI product you use.
 
 |                         | You pay for...                               | Result                               |
 | ----------------------- | -------------------------------------------- | ------------------------------------ |
 | AI subscription       | Access. Paid whether you use it or not. | $20–200/month, rate-limited.         |
 | Pay-per-call (OpenAI API, etc.) | Every attempt — even failed ones.    | Hidden cost from retries, dead ends. |
-| **Franklin (YOPO)**     | **The outcome.** Each signed micropayment.  | **Provider cost + 5%. No more.**     |
+| **Franklin Agent (YOPO)**     | **The outcome.** Each signed micropayment.  | **Provider cost + 5%. No more.**     |
 
 Three consequences fall out of this:
 

package/dist/agent/commands.js

@@ -177,8 +177,25 @@ const DIRECT_COMMANDS = {
                 if ('type' in part) {
                     if (part.type === 'tool_result') {
                         toolResults++;
-                        const c = typeof part.content === 'string' ? part.content : JSON.stringify(part.content);
-                        totalToolChars += c.length;
+                        // Sibling of PR #54's tokens.ts fix: image base64 must NOT
+                        // count toward the displayed char total — `/context` would
+                        // otherwise show ~70K chars per attached image and confuse
+                        // the user about why the ring is at 1% but "total tool
+                        // chars" is huge.
+                        if (typeof part.content === 'string') {
+                            totalToolChars += part.content.length;
+                        }
+                        else if (Array.isArray(part.content)) {
+                            for (const block of part.content) {
+                                const t = block.type;
+                                if (t === 'text') {
+                                    totalToolChars += (block.text || '').length;
+                                }
+                                else if (t === 'image') {
+                                    totalToolChars += 6000; // ~1500 tokens × 4 chars/tok
+                                }
+                            }
+                        }
                     }
                     if (part.type === 'thinking')
                         thinkingBlocks++;

package/dist/agent/compact.js

@@ -385,7 +385,36 @@ function formatForSummarization(messages) {
                             textParts.push(`[Called tool: ${part.name}(${JSON.stringify(part.input).slice(0, 200)})]`);
                             break;
                         case 'tool_result': {
-                            const content = typeof part.content === 'string' ? part.content : JSON.stringify(part.content);
+                            // Sibling of PR #54's tokens.ts fix: when content is a
+                            // [{text}, {image}] array, JSON.stringify dumps base64
+                            // bytes into the summary prompt — bloats the summarizer's
+                            // input and produces a useless preview ("[Tool result:
+                            // [{\"type\":\"text\",\"text\":\"Image file: ...\"},{\"type\":\"image\",\"source\":{\"type\":\"base64\",\"data\":\"...").
+                            // Build the preview from text blocks only; mark images
+                            // explicitly so the summarizer knows they exist.
+                            let content;
+                            if (typeof part.content === 'string') {
+                                content = part.content;
+                            }
+                            else if (Array.isArray(part.content)) {
+                                const pieces = [];
+                                let imageCount = 0;
+                                for (const block of part.content) {
+                                    const t = block.type;
+                                    if (t === 'text') {
+                                        pieces.push(block.text || '');
+                                    }
+                                    else if (t === 'image') {
+                                        imageCount++;
+                                    }
+                                }
+                                if (imageCount > 0)
+                                    pieces.push(`[${imageCount} image block${imageCount > 1 ? 's' : ''}]`);
+                                content = pieces.join(' ');
+                            }
+                            else {
+                                content = JSON.stringify(part.content);
+                            }
                             const truncated = content.length > 500 ? content.slice(0, 500) + '...' : content;
                             textParts.push(`[Tool result${part.is_error ? ' (ERROR)' : ''}: ${truncated}]`);
                             break;

package/dist/agent/loop.js

@@ -1585,7 +1585,11 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 tier: routingTier,
                 confidence: routingConfidence,
                 savings: routingSavings,
-                contextPct: Math.round(contextUsagePct),
+                // Preserve sub-1% precision: a fresh session at 0.4% would
+                // round to 0 and freeze the renderer's context ring until the
+                // conversation grows past ~1k tokens. Match `/context`'s
+                // `.toFixed(1)` fidelity.
+                contextPct: Math.round(contextUsagePct * 10) / 10,
             });
             // Record usage for stats tracking (franklin stats command).
             // Prefer the real x402 charge from the gateway over a token-catalog

package/dist/agent/reduce.js

@@ -458,7 +458,27 @@ function estimateChars(history) {
                     if (p.type === 'text')
                         total += p.text.length;
                     else if (p.type === 'tool_result') {
-                        total += typeof p.content === 'string' ? p.content.length : JSON.stringify(p.content).length;
+                        // Sibling of PR #54's tokens.ts fix: JSON.stringify-ing a
+                        // [{text}, {image}] array counts the base64 `data` field as
+                        // text and inflates the char count by ~70K per image. That
+                        // skews every reduce-pass decision (when to dedupe, when to
+                        // collapse) toward "save chars by collapsing the image-
+                        // bearing result" — exactly wrong. Walk blocks instead.
+                        if (typeof p.content === 'string') {
+                            total += p.content.length;
+                        }
+                        else if (Array.isArray(p.content)) {
+                            for (const block of p.content) {
+                                if (block.type === 'text') {
+                                    total += (block.text || '').length;
+                                }
+                                else if (block.type === 'image') {
+                                    // Mirror tokens.ts: image ≈ 1500 tokens ≈ ~6K chars
+                                    // at the 4-chars/token rule estimateTokens uses.
+                                    total += 6000;
+                                }
+                            }
+                        }
                     }
                     else if (p.type === 'tool_use') {
                         total += JSON.stringify(p.input).length;

package/dist/agent/tokens.js

@@ -45,6 +45,11 @@ export function updateActualTokens(inputTokens, outputTokens, messageCount) {
  * More accurate than pure estimation because it's grounded in actual API counts.
  */
 export function getAnchoredTokenCount(history) {
+    // The model that just billed input — used as the denominator below.
+    // _currentModel is set per-turn by setEstimationModel(), so it reflects
+    // whatever the router actually resolved (not just config.model, which
+    // may be a routing profile like blockrun/auto).
+    const contextWindow = _currentModel ? getContextWindow(_currentModel) : 200_000;
     if (lastApiInputTokens > 0 && lastApiMessageCount > 0 && history.length >= lastApiMessageCount) {
         // Sanity check: if history was mutated (compaction, micro-compact), anchor may be stale.
         // Detect by checking if new messages were only appended (length grew), not if content changed.
@@ -60,17 +65,18 @@ export function getAnchoredTokenCount(history) {
             return {
                 estimated: total,
                 apiAnchored: true,
-                contextUsagePct: 0,
+                contextUsagePct: (total / contextWindow) * 100,
             };
         }
         // Too much growth — anchor is unreliable, fall through to estimation
         resetTokenAnchor();
     }
     // No anchor — pure estimation
+    const est = estimateHistoryTokens(history);
     return {
-        estimated: estimateHistoryTokens(history),
+        estimated: est,
         apiAnchored: false,
-        contextUsagePct: 0,
+        contextUsagePct: (est / contextWindow) * 100,
     };
 }
 /**
@@ -115,10 +121,40 @@ function estimateContentPartTokens(part) {
             // +16 tokens for tool_use framing (type, id, name fields, JSON structure)
             return 16 + estimateTokens(part.name) + estimateTokens(JSON.stringify(part.input), 2);
         case 'tool_result': {
-            const content = typeof part.content === 'string'
-                ? part.content
-                : JSON.stringify(part.content);
-            return estimateTokens(content, 2);
+            // String content: count as text directly.
+            if (typeof part.content === 'string') {
+                return estimateTokens(part.content, 2);
+            }
+            // Array content: sum block-by-block. CRITICAL: image blocks must
+            // NOT go through JSON.stringify — their base64 `data` field would
+            // be tokenized as text (a 100KB image → ~70k phantom tokens),
+            // which is what made the context ring read ~86% on a 2-image chat
+            // and triggered premature /compact loops. Anthropic actually
+            // bills (w*h)/750 per image, ≈1100-1500 for typical sizes; a flat
+            // 1500-token estimate is close enough without needing to decode
+            // the image dimensions client-side.
+            let total = 0;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const blocks = part.content;
+            for (const block of blocks) {
+                const blockType = block?.type;
+                if (blockType === 'text') {
+                    total += estimateTokens(block?.text ?? '', 2);
+                }
+                else if (blockType === 'image') {
+                    total += 1500;
+                }
+                else {
+                    // Unknown block — stringify minus any nested base64 data field
+                    // to avoid the same blow-up for future block kinds.
+                    const sanitized = { ...block };
+                    if (sanitized?.source && typeof sanitized.source === 'object' && sanitized.source.data) {
+                        sanitized.source = { ...sanitized.source, data: '<bytes>' };
+                    }
+                    total += estimateTokens(JSON.stringify(sanitized), 2);
+                }
+            }
+            return total;
         }
         case 'thinking':
             return estimateTokens(part.thinking);

package/dist/banner.js

@@ -113,7 +113,7 @@ export function printBanner(version) {
 }
 function printCompactBanner(version) {
     const title = chalk.bold.hex(GOLD_START)('FRANKLIN');
-    const meta = chalk.dim(`  ·  blockrun.ai  ·  v${version}`);
+    const meta = chalk.dim(` Agent  ·  blockrun.ai  ·  v${version}`);
     console.log(`${title}${meta}`);
     console.log(chalk.dim('The AI agent with a wallet'));
     console.log('');

package/package.json

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