@blockrun/franklin 3.3.3 → 3.5.1

package/README.md

@@ -29,6 +29,7 @@
   <a href="#quick-start">Quick&nbsp;start</a> ·
   <a href="#a-new-category">New&nbsp;category</a> ·
   <a href="#what-franklin-can-execute">What&nbsp;it&nbsp;does</a> ·
+  <a href="#smart-router">Smart&nbsp;Router</a> ·
   <a href="#the-comparison">Compare</a> ·
   <a href="#features">Features</a> ·
   <a href="#how-it-works">Architecture</a> ·
@@ -120,31 +121,20 @@ Franklin is **chat-first**. You do not wire a DAG, configure six API keys, or co
 
 Live data from CoinGecko. RSI, MACD, Bollinger, and volatility computed locally. No API key needed.
 
-### 🎯 Social growth
+### 🎨 Image generation
 
 ```text
-> find X posts complaining about AI rate limits
+> generate a logo for my AI startup — minimalist, dark background
 
-  ✓ SearchX  "AI rate limits"
-
-  Found 8 candidates:
-  1. "Claude keeps throttling me in the middle of shipping..." — @buildermax (2h)
-  2. "I need an agent that can switch models automatically." — @indiedev (5h)
-  ...
-
-> write a reply to #2 — mention Franklin uses a wallet instead of subscriptions
+  ✓ ImageGen  "minimalist AI startup logo, dark background..."
+  Saved: generated-logo-1713052800.png (1024x1024)
+```
 
-  Draft:
-  "That was my pain too. Franklin routes across 55+ models,
-   pays per action from a USDC wallet, and doesn't trap you
-   inside a monthly seat. Better economics, better uptime."
+Generates images via DALL-E / GPT Image directly from the CLI. Paid from your wallet — no OpenAI API key needed.
 
-> looks good, post it
+### 🎯 Social growth (with setup)
 
-  ✓ PostToX  Reply posted to x.com/indiedev/status/...
-```
-
-Search X, generate contextual replies, and post with confirmation. Uses Playwright for browser automation, so there is no X API key, no OAuth maze, and no $100/month developer account.
+After running `franklin social setup && franklin social login x`, Franklin can search X, draft replies, and post with your confirmation — no X API key or developer account needed.
 
 ### 🔎 Research, code, anything with a budget
 
@@ -179,6 +169,52 @@ Every tool call is itemized. Every token is priced. When the wallet hits zero, F
 
 ---
 
+## Smart Router
+
+**55+ models. One decision. Zero guesswork.**
+
+You don't pick models. Franklin picks for you.
+
+The Smart Router classifies every request — coding, trading, reasoning, research — and selects the model with the best quality-to-cost ratio. Trained on **2M+ real requests** from the BlockRun gateway, continuously updated.
+
+```text
+> refactor this auth module to use JWT
+
+  CODING kimi-k2.5  ·  12.4K in / 2.1K out  ·  $0.0023  saved 84%
+
+> what's the BTC outlook for the week?
+
+  TRADING grok-4-1-fast-reasoning  ·  8.2K in / 1.8K out  ·  $0.0008  saved 95%
+
+> prove that this algorithm is O(n log n)
+
+  REASONING claude-sonnet-4.6  ·  15.1K in / 3.4K out  ·  $0.0312
+```
+
+Every response shows which model was chosen, why, and how much you saved vs. always using the most expensive option.
+
+**Four profiles:**
+
+| Profile | Strategy | Use case |
+|---------|----------|----------|
+| `auto` | Best quality-to-cost ratio | Default — smart spend |
+| `eco` | Cheapest model with decent quality | Budget-conscious |
+| `premium` | Highest quality regardless of cost | Mission-critical |
+| `free` | Free NVIDIA models only | Zero wallet balance |
+
+**Per-session breakdown** — run `/cost` to see exactly where your USDC went:
+
+```text
+Session Cost: $0.0847 (23 requests)
+  gemini-2.5-flash       $0.0012   14 req   CODING
+  kimi-k2.5              $0.0423    6 req   CODING
+  claude-sonnet-4.6      $0.0412    3 req   REASONING
+```
+
+The router also learns from **your** usage. If you keep retrying a model for coding tasks, Franklin adapts and picks a better one next time. Your router gets smarter the more you use it.
+
+---
+
 ## Why Franklin
 
 <table>
@@ -215,6 +251,7 @@ Marketing, trading, research, code, and anything else you can express as tools p
 | ------------------------------------ | --------------- | ---------------- | ---------------- | ------------------------------- |
 | Main unit of value                   | Answers         | Code changes     | Fixed automations| **Budgeted outcomes**           |
 | Has purchasing power                 | ❌              | ❌               | ❌               | ✅ **wallet-native**            |
+| Picks best model per task            | ❌              | ❌               | ❌               | ✅ **learned router**           |
 | Can choose tools/models per step     | ⚠️ limited      | ✅ mostly coding | ❌ usually fixed | ✅ **yes**                      |
 | Works across marketing/trading/code  | ⚠️              | ❌ code-first    | ⚠️ integration-bound | ✅ **cross-vertical**       |
 | Hard spend cap                       | ❌              | ❌               | ⚠️ external billing | ✅ **wallet balance**        |
@@ -238,8 +275,8 @@ Franklin can decide what is worth paying for, route the call, sign the micropaym
 **📈 Trading signals**
 Ask "what's BTC looking like?" — Franklin fetches live price data, computes RSI/MACD/Bollinger/volatility, and synthesizes a signal.
 
-**🎯 Social growth**
-Ask "find X posts about my category" — Franklin searches X, drafts replies, and posts with your confirmation.
+**🎨 AI image generation**
+Ask "generate a logo" — Franklin calls DALL-E / GPT Image, saves the result locally, paid from your wallet.
 
 **🧠 55+ models via one wallet**
 Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One wallet, one interface, automatic fallback.
@@ -247,8 +284,8 @@ Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier.
 **💳 x402 micropayments**
 HTTP 402 native. Every paid action is a signed micropayment against your USDC balance. No subscriptions. No refund loop. No account lock-in.
 
-**🚦 Smart spend routing**
-Free / cheap / premium per step. Franklin picks the cheapest model that can do the job, then escalates when quality matters.
+**🧠 Learned model router**
+Trained on 2M+ real requests. Classifies your task and picks the best model from 55+ LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
 
 </td>
 <td width="50%" valign="top">
@@ -301,7 +338,10 @@ Core is workflow-agnostic. Add new verticals without touching the loop. Discover
 ```text
 ┌──────────────────────────────────────────────────────────────┐
 │  Franklin Runtime                                            │
-│  Intent → Routing → Tool Use → Spend Decisions → Result      │
+│  Intent → Smart Router → Tool Use → Spend Control → Result   │
+├──────────────────────────────────────────────────────────────┤
+│  Learned Router                                              │
+│  2M+ requests · 55+ models · category detection · Elo scores │
 ├──────────────────────────────────────────────────────────────┤
 │  Agent Loop                                                  │
 │  16 tools · Sessions · Compaction · Pricing · Plugin SDK     │
@@ -349,7 +389,7 @@ src/
 ├── stats/             Usage tracking + insights engine
 ├── ui/                Ink-based terminal UI
 ├── proxy/             Payment proxy for external tools
-├── router/            Smart model routing (free/cheap/premium)
+├── router/            Learned model router (2M+ requests, Elo scoring)
 ├── wallet/            Wallet management (Base + Solana)
 ├── mcp/               MCP server auto-discovery
 └── commands/          CLI subcommands

package/dist/agent/commands.d.ts

@@ -1,5 +1,5 @@
 /**
- * Slash command registry for runcode.
+ * Slash command registry for Franklin.
  * Extracted from loop.ts for maintainability.
  *
  * Two types of commands:

package/dist/agent/commands.js

@@ -1,5 +1,5 @@
 /**
- * Slash command registry for runcode.
+ * Slash command registry for Franklin.
  * Extracted from loop.ts for maintainability.
  *
  * Two types of commands:
@@ -104,8 +104,13 @@ function extractText(msg) {
 // ─── Command Definitions ──────────────────────────────────────────────────
 // Direct-handled commands (don't go to agent)
 const DIRECT_COMMANDS = {
+    '/noplan': (ctx) => {
+        ctx.config.planDisabled = true;
+        ctx.onEvent({ kind: 'text_delta', text: 'Plan-then-execute disabled for this session. Complex tasks will use a single model.\n' });
+        emitDone(ctx);
+    },
     '/stash': (ctx) => {
-        const r = gitCmd(ctx, 'git stash push -m "runcode auto-stash"', 10000);
+        const r = gitCmd(ctx, 'git stash push -m "franklin auto-stash"', 10000);
         if (r !== null)
             ctx.onEvent({ kind: 'text_delta', text: r ? `${r}\n` : 'No changes to stash.\n' });
         emitDone(ctx);
@@ -197,8 +202,8 @@ const DIRECT_COMMANDS = {
                 `  **Git:** /push /pr /undo /status /diff /log /branch /stash /unstash\n` +
                 `  **Analysis:** /security /lint /optimize /todo /deps /clean /migrate /doc\n` +
                 `  **Session:** /plan /ultraplan /execute /compact /retry /sessions /resume /session-search /context /tasks\n` +
-                `  **Power:** /ultrathink [query] /ultraplan /dump\n` +
-                `  **Info:** /model /wallet /cost /tokens /learnings /mcp /doctor /version /bug /help\n` +
+                `  **Power:** /ultrathink [query] /ultraplan /noplan /dump\n` +
+                `  **Info:** /model /wallet /cost /tokens /learnings /brain /mcp /doctor /version /bug /help\n` +
                 `  **UI:** /clear /exit\n` +
                 (ultrathinkOn ? `\n  Ultrathink: ON\n` : '')
         });
@@ -225,7 +230,7 @@ const DIRECT_COMMANDS = {
         emitDone(ctx);
     },
     '/bug': (ctx) => {
-        ctx.onEvent({ kind: 'text_delta', text: 'Report issues at: https://github.com/BlockRunAI/runcode/issues\n' });
+        ctx.onEvent({ kind: 'text_delta', text: 'Report issues at: https://github.com/BlockRunAI/Franklin/issues\n' });
         emitDone(ctx);
     },
     '/version': (ctx) => {
@@ -340,34 +345,57 @@ const DIRECT_COMMANDS = {
         }
         emitDone(ctx);
     },
-    '/sessions': (ctx) => {
+    '/sessions': async (ctx) => {
         const sessions = listSessions();
         if (sessions.length === 0) {
             ctx.onEvent({ kind: 'text_delta', text: 'No saved sessions.\n' });
         }
         else {
+            const { formatTokens, formatUsd, shortModelName } = await import('../stats/format.js');
             let text = `**${sessions.length} saved sessions:**\n\n`;
             for (const s of sessions.slice(0, 10)) {
                 const date = new Date(s.updatedAt).toLocaleString();
-                const dir = s.workDir ? ` — ${s.workDir.split('/').pop()}` : '';
-                const current = s.id === ctx.sessionId ? '  (current)' : '';
-                text += `  ${s.id}  ${s.model}  ${s.turnCount} turns  ${date}${dir}${current}\n`;
+                const dir = s.workDir ? path.basename(s.workDir) : '';
+                const current = s.id === ctx.sessionId ? ' (current)' : '';
+                const model = shortModelName(s.model);
+                const tokens = (s.inputTokens || s.outputTokens)
+                    ? `  ${formatTokens(s.inputTokens ?? 0)} in / ${formatTokens(s.outputTokens ?? 0)} out`
+                    : '';
+                const cost = s.costUsd ? `  ${formatUsd(s.costUsd)}` : '';
+                const saved = s.savedVsOpusUsd && s.savedVsOpusUsd > 0.001
+                    ? `  saved ${formatUsd(s.savedVsOpusUsd)}`
+                    : '';
+                text += `  ${model} — ${s.messageCount} messages${tokens}${cost}${saved}\n`;
+                text += `  ${date} · ${dir}${current}\n\n`;
             }
             if (sessions.length > 10)
                 text += `  ... and ${sessions.length - 10} more\n`;
-            text += '\nUse /resume to restore the latest session, or /resume <session-id> for a specific one.\n';
+            text += 'Use /resume to restore the latest session, or /resume <session-id> for a specific one.\n';
             ctx.onEvent({ kind: 'text_delta', text });
         }
         emitDone(ctx);
     },
     '/cost': async (ctx) => {
         const { stats, saved } = getStatsSummary();
-        ctx.onEvent({ kind: 'text_delta', text: `**Session Cost**\n` +
-                `  Requests: ${stats.totalRequests}\n` +
-                `  Cost:     $${stats.totalCostUsd.toFixed(4)} USDC\n` +
-                `  Saved:    $${saved.toFixed(2)} vs Claude Opus\n` +
-                `  Tokens:   ${stats.totalInputTokens.toLocaleString()} in / ${stats.totalOutputTokens.toLocaleString()} out\n`
-        });
+        const { getSessionModelBreakdown } = await import('../stats/session-tracker.js');
+        const { formatTokens, formatUsd, shortModelName } = await import('../stats/format.js');
+        const breakdown = getSessionModelBreakdown();
+        let text = `**Session Cost**\n` +
+            `  Requests: ${stats.totalRequests}\n` +
+            `  Cost:     $${stats.totalCostUsd.toFixed(4)} USDC\n` +
+            `  Saved:    $${saved.toFixed(2)} vs Claude Opus\n` +
+            `  Tokens:   ${formatTokens(stats.totalInputTokens)} in / ${formatTokens(stats.totalOutputTokens)} out\n`;
+        if (breakdown.length > 0) {
+            text += `\n  **By model:**\n`;
+            for (const m of breakdown) {
+                const name = shortModelName(m.model).padEnd(28);
+                const cost = formatUsd(m.costUsd).padStart(8);
+                const reqs = `${m.requests} req`.padStart(6);
+                const tier = m.lastTier ? `  ${m.lastTier}` : '';
+                text += `    ${name} ${cost}  ${reqs}${tier}\n`;
+            }
+        }
+        ctx.onEvent({ kind: 'text_delta', text });
         emitDone(ctx);
     },
     '/wallet': async (ctx) => {
@@ -419,6 +447,38 @@ const DIRECT_COMMANDS = {
         ctx.onEvent({ kind: 'text_delta', text: 'Conversation history cleared.\n' });
         emitDone(ctx);
     },
+    '/failures': async (ctx) => {
+        const { getFailureStats } = await import('../stats/failures.js');
+        const stats = getFailureStats();
+        if (stats.total === 0) {
+            ctx.onEvent({ kind: 'text_delta', text: 'No failures recorded.\n' });
+            emitDone(ctx);
+            return;
+        }
+        let text = `**Failure Log** (${stats.total} total)\n\n`;
+        if (stats.byType.size > 0) {
+            text += '  **By type:**\n';
+            for (const [type, count] of [...stats.byType.entries()].sort((a, b) => b[1] - a[1])) {
+                text += `    ${type.padEnd(20)} ${count}\n`;
+            }
+        }
+        if (stats.byTool.size > 0) {
+            text += '\n  **By tool:**\n';
+            for (const [tool, count] of [...stats.byTool.entries()].sort((a, b) => b[1] - a[1])) {
+                text += `    ${tool.padEnd(20)} ${count}\n`;
+            }
+        }
+        if (stats.recentFailures.length > 0) {
+            text += '\n  **Recent:**\n';
+            for (const f of stats.recentFailures.slice(-5)) {
+                const date = new Date(f.timestamp).toLocaleDateString();
+                const tool = f.toolName ? ` ${f.toolName}:` : '';
+                text += `    [${date}]${tool} ${f.errorMessage.slice(0, 80)}\n`;
+            }
+        }
+        ctx.onEvent({ kind: 'text_delta', text });
+        emitDone(ctx);
+    },
     '/compact': async (ctx) => {
         const beforeTokens = estimateHistoryTokens(ctx.history);
         const { history: compacted, compacted: didCompact } = await forceCompact(ctx.history, ctx.config.model, ctx.client, ctx.config.debug);
@@ -546,6 +606,57 @@ export async function handleSlashCommand(input, ctx) {
         emitDone(ctx);
         return { handled: true };
     }
+    // /brain — view knowledge graph entities
+    if (input === '/brain' || input.startsWith('/brain ')) {
+        const { searchEntities, loadEntities, getEntityObservations, getEntityRelations, getBrainStats, loadObservations } = await import('../brain/store.js');
+        const arg = input.slice('/brain'.length).trim();
+        if (!arg) {
+            const stats = getBrainStats();
+            if (stats.entities === 0) {
+                ctx.onEvent({ kind: 'text_delta', text: 'Brain is empty. Franklin learns entities (people, projects, companies) from your conversations over time.\n' });
+            }
+            else {
+                const entities = loadEntities().sort((a, b) => b.reference_count - a.reference_count);
+                let text = `**Franklin Brain** (${stats.entities} entities, ${stats.observations} facts, ${stats.relations} relations)\n\n`;
+                for (const e of entities.slice(0, 20)) {
+                    text += `  ${e.type === 'person' ? '👤' : e.type === 'company' ? '🏢' : e.type === 'project' ? '📦' : '💡'} **${e.name}** (${e.type}, ×${e.reference_count})\n`;
+                }
+                if (entities.length > 20)
+                    text += `  ... and ${entities.length - 20} more\n`;
+                text += '\nSearch: `/brain <name>` for details.\n';
+                ctx.onEvent({ kind: 'text_delta', text });
+            }
+        }
+        else {
+            const results = searchEntities(arg, 5);
+            if (results.length === 0) {
+                ctx.onEvent({ kind: 'text_delta', text: `No entities matching "${arg}".\n` });
+            }
+            else {
+                let text = '';
+                for (const e of results) {
+                    text += `**${e.name}** (${e.type})\n`;
+                    if (e.aliases.length > 0)
+                        text += `  Aliases: ${e.aliases.join(', ')}\n`;
+                    const obs = getEntityObservations(e.id).slice(0, 5);
+                    for (const o of obs) {
+                        text += `  - ${o.content}\n`;
+                    }
+                    const rels = getEntityRelations(e.id);
+                    const allEntities = loadEntities();
+                    for (const r of rels.slice(0, 3)) {
+                        const other = allEntities.find(x => x.id === (r.from_id === e.id ? r.to_id : r.from_id));
+                        if (other)
+                            text += `  → ${r.type} ${other.name}\n`;
+                    }
+                    text += '\n';
+                }
+                ctx.onEvent({ kind: 'text_delta', text });
+            }
+        }
+        emitDone(ctx);
+        return { handled: true };
+    }
     // /model — show current model or switch with /model <name>
     if (input === '/model' || input.startsWith('/model ')) {
         if (input === '/model') {
@@ -677,7 +788,7 @@ export async function handleSlashCommand(input, ctx) {
         ...Object.keys(DIRECT_COMMANDS),
         ...Object.keys(REWRITE_COMMANDS),
         ...ARG_COMMANDS.map(c => c.prefix.trim()),
-        '/branch', '/resume', '/model', '/wallet', '/cost', '/help', '/clear', '/retry', '/exit', '/session-search', '/ssearch',
+        '/branch', '/resume', '/model', '/wallet', '/cost', '/help', '/clear', '/retry', '/exit', '/session-search', '/ssearch', '/failures',
     ];
     const cmd = input.split(/\s/)[0];
     const close = allCommands.filter(c => {

package/dist/agent/compact.d.ts

@@ -1,11 +1,11 @@
 /**
- * Context compaction for runcode.
+ * Context compaction for Franklin.
  * When conversation history approaches the context window limit,
  * summarize older messages and replace them with the summary.
  */
 import { ModelClient } from './llm.js';
 import type { Dialogue } from './types.js';
-export declare const COMPACT_HEADER = "[CONTEXT COMPACTION] Earlier turns in this conversation were compacted to save context space. The summary below describes work that was already completed, and the current session state may still reflect that work (for example, files may already be changed). Use the summary and the current state to continue from where things left off, and avoid repeating work:";
+export declare const COMPACT_HEADER = "[CONTEXT COMPACTION \u2014 REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window \u2014 treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Respond ONLY to the latest user message that appears AFTER this summary.";
 /**
  * Check if compaction is needed and perform it if so.
  * Returns the (possibly compacted) history.