@blockrun/franklin 3.3.3 → 3.5.0

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> ·
@@ -179,6 +180,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 +262,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**        |
@@ -247,8 +295,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 +349,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 +400,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.

package/dist/agent/compact.js

@@ -1,48 +1,64 @@
 /**
- * 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 { existsSync, readFileSync } from 'node:fs';
 import { estimateHistoryTokens, getCompactionThreshold, COMPACTION_SUMMARY_RESERVE, } from './tokens.js';
+/** Max files to restore after compaction (inspired by Claude Code POST_COMPACT_MAX_FILES_TO_RESTORE) */
+const POST_COMPACT_MAX_FILES = 5;
+/** Max tokens to spend on post-compact file restoration */
+const POST_COMPACT_TOKEN_BUDGET = 50_000;
 // Structured compaction prompt (pattern from nousresearch/hermes-agent
 // `agent/context_compressor.py`). The structured sections preserve more
 // signal than free-form summaries and make it easier for the model to
 // continue work from where it left off.
-export 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 const COMPACT_HEADER = `[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window — 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.`;
 const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Produce a STRUCTURED summary of the conversation so far that preserves all decision-relevant context for continuing the task.
 
+CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
+
 Critical rules:
 - Preserve EXACT file paths, function names, line numbers, variable names
-- Preserve EXACT error messages (verbatim)
+- Preserve EXACT error messages and stack traces (verbatim)
 - Preserve user preferences and corrections (especially "don't do X" instructions)
 - Preserve decisions with their rationale (not just the decision)
+- Include full code snippets and function signatures when they are load-bearing
 - DO NOT include reasoning that led to decisions — only the decisions themselves
 - DO NOT include pleasantries, meta-commentary, or apologies
 - Use bullet points inside each section
 - Be specific: "edited src/foo.ts:42 to add error handling" not "made some changes"
 
-REQUIRED output format (use these exact section headers):
+First, analyze the conversation chronologically inside <analysis> tags. This is your drafting space — it will be stripped from the final output. Think through what matters before writing the summary.
+
+Then produce the summary inside <summary> tags using these exact section headers:
 
 ## Goal
 [One clear sentence: what the user is trying to accomplish]
 
+## Key Technical Context
+[Important technical details, architecture patterns, constraints, or domain knowledge established during the conversation that future work depends on]
+
 ## Progress
-[Chronological bullet list of what has been done so far]
+[Chronological bullet list of what has been done so far, with specific file paths and line numbers]
+
+## Errors and Fixes
+[Any errors encountered, their root causes, and how they were resolved — this prevents re-investigating the same issues]
 
 ## Decisions
 [Key decisions made, each with its rationale]
 
 ## Files Modified
-[Each file touched, with a one-line description of what changed]
+[Each file touched, with a one-line description of what changed and why]
 
 ## Tool Results Still Relevant
-[Any tool output (file reads, grep matches, bash output) that later steps still depend on — include the actual content, not a reference]
+[Any tool output (file reads, grep matches, bash output) that later steps still depend on — include the actual content, not just a reference to it]
 
-## User Preferences & Corrections
-[Anything the user explicitly asked for or corrected — these are load-bearing]
+## User Messages and Feedback
+[Chronological summary of what the user said, asked for, and corrected — these are load-bearing and must not be lost]
 
 ## Next Steps
-[What comes next, in priority order]
+[What comes next, in priority order, with enough detail to continue without re-reading the original conversation]
 
 If there's an existing [CONTEXT COMPACTION] summary in the messages being compacted, MERGE its content into your output rather than nesting. Do not produce a summary of a summary.`;
 /**
@@ -56,7 +72,7 @@ export async function autoCompactIfNeeded(history, model, client, debug) {
         return { history, compacted: false };
     }
     if (debug) {
-        console.error(`[runcode] Auto-compacting: ~${currentTokens} tokens, threshold=${threshold}`);
+        console.error(`[franklin] Auto-compacting: ~${currentTokens} tokens, threshold=${threshold}`);
     }
     const beforeTokens = estimateHistoryTokens(history);
     try {
@@ -64,7 +80,7 @@ export async function autoCompactIfNeeded(history, model, client, debug) {
         const afterTokens = estimateHistoryTokens(compacted);
         if (afterTokens >= beforeTokens) {
             if (debug) {
-                console.error(`[runcode] Auto-compaction grew history (${beforeTokens} → ${afterTokens}) — skipping`);
+                console.error(`[franklin] Auto-compaction grew history (${beforeTokens} → ${afterTokens}) — skipping`);
             }
             return { history, compacted: false };
         }
@@ -72,7 +88,7 @@ export async function autoCompactIfNeeded(history, model, client, debug) {
     }
     catch (err) {
         if (debug) {
-            console.error(`[runcode] Compaction failed: ${err.message}`);
+            console.error(`[franklin] Compaction failed: ${err.message}`);
         }
         // Fallback: truncate oldest messages instead of crashing
         const truncated = emergencyTruncate(history, threshold);
@@ -93,7 +109,7 @@ export async function forceCompact(history, model, client, debug) {
         // Only accept compaction if it actually reduces tokens
         if (afterTokens >= beforeTokens) {
             if (debug) {
-                console.error(`[runcode] Compaction produced larger history (${beforeTokens} → ${afterTokens}) — reverting`);
+                console.error(`[franklin] Compaction produced larger history (${beforeTokens} → ${afterTokens}) — reverting`);
             }
             return { history, compacted: false };
         }
@@ -101,7 +117,7 @@ export async function forceCompact(history, model, client, debug) {
     }
     catch (err) {
         if (debug) {
-            console.error(`[runcode] Force compaction failed: ${err.message}`);
+            console.error(`[franklin] Force compaction failed: ${err.message}`);
         }
         const threshold = getCompactionThreshold(model);
         const truncated = emergencyTruncate(history, threshold);
@@ -124,7 +140,7 @@ async function compactHistory(history, model, client, debug) {
         return history;
     }
     if (debug) {
-        console.error(`[runcode] Summarizing ${toSummarize.length} messages, keeping ${toKeep.length}`);
+        console.error(`[franklin] Summarizing ${toSummarize.length} messages, keeping ${toKeep.length}`);
     }
     // Build summary request
     const summaryMessages = [
@@ -140,16 +156,17 @@ async function compactHistory(history, model, client, debug) {
         max_tokens: COMPACTION_SUMMARY_RESERVE,
         stream: true,
     });
-    // Extract summary text
-    let summaryText = '';
+    // Extract summary text and strip analysis scratchpad
+    let rawSummary = '';
     for (const part of summaryParts) {
         if (part.type === 'text') {
-            summaryText += part.text;
+            rawSummary += part.text;
         }
     }
-    if (!summaryText) {
+    if (!rawSummary) {
         throw new Error('Empty summary returned from model');
     }
+    const summaryText = formatCompactSummary(rawSummary);
     // Build compacted history: summary as first message, then kept messages.
     // The COMPACT_HEADER prefix lets future compactions detect and merge rather
     // than nest summaries.
@@ -162,14 +179,107 @@ async function compactHistory(history, model, client, debug) {
             role: 'assistant',
             content: 'Got it. I have the structured context from earlier work and will continue from where things left off.',
         },
-        ...toKeep,
     ];
+    // Post-compact file restoration (inspired by Claude Code)
+    // Re-read recently modified files to restore working context that was lost
+    // during compaction. This prevents the agent from needing to re-read files
+    // it was actively working on.
+    const restoredFiles = restoreRecentFiles(summaryText, toSummarize, debug);
+    if (restoredFiles) {
+        compacted.push({ role: 'user', content: restoredFiles.prompt }, { role: 'assistant', content: 'I have the restored file contents and will use them as context for continuing work.' });
+    }
+    compacted.push(...toKeep);
     if (debug) {
         const newTokens = estimateHistoryTokens(compacted);
-        console.error(`[runcode] Compacted: ${estimateHistoryTokens(history)} → ${newTokens} tokens`);
+        console.error(`[franklin] Compacted: ${estimateHistoryTokens(history)} → ${newTokens} tokens`);
     }
     return compacted;
 }
+/**
+ * Restore recently modified files after compaction.
+ * Extracts file paths from the compaction summary and the original messages,
+ * reads the ones that still exist, and builds a context restoration prompt.
+ *
+ * Inspired by Claude Code's POST_COMPACT_MAX_FILES_TO_RESTORE mechanism.
+ */
+function restoreRecentFiles(summaryText, compactedMessages, debug) {
+    // Extract file paths from multiple sources:
+    // 1. "Files Modified" section in the summary
+    // 2. Edit/Write/Read tool calls in the compacted messages
+    const filePaths = new Set();
+    // Source 1: Parse "## Files Modified" section from summary
+    const filesSection = summaryText.match(/## Files Modified\n([\s\S]*?)(?=\n## |$)/);
+    if (filesSection) {
+        const pathRegex = /[`"]?([/\w.-]+\.\w{1,10})[`"]?/g;
+        let match;
+        while ((match = pathRegex.exec(filesSection[1])) !== null) {
+            const p = match[1];
+            // Filter: must look like a real file path (has directory separator or extension)
+            if (p.includes('/') || p.includes('.')) {
+                filePaths.add(p);
+            }
+        }
+    }
+    // Source 2: Extract from Edit/Write tool_use inputs in compacted messages
+    for (const msg of compactedMessages) {
+        if (msg.role !== 'assistant' || !Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (part.type === 'tool_use' && (part.name === 'Edit' || part.name === 'Write')) {
+                const fp = part.input?.file_path;
+                if (typeof fp === 'string' && fp.startsWith('/')) {
+                    filePaths.add(fp);
+                }
+            }
+        }
+    }
+    if (filePaths.size === 0)
+        return null;
+    // Prioritize: most recently modified files first, limit to POST_COMPACT_MAX_FILES
+    const candidates = [...filePaths].filter(p => {
+        try {
+            return existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (candidates.length === 0)
+        return null;
+    // Read files within token budget
+    const restoredParts = [];
+    let tokenBudget = POST_COMPACT_TOKEN_BUDGET;
+    const filesToRestore = candidates.slice(0, POST_COMPACT_MAX_FILES);
+    for (const fp of filesToRestore) {
+        try {
+            const content = readFileSync(fp, 'utf-8');
+            const estimatedTokens = Math.ceil(content.length / 4 * 1.33);
+            if (estimatedTokens > tokenBudget) {
+                // File too large for remaining budget — take first chunk
+                const maxChars = Math.floor(tokenBudget * 3); // ~3 chars per token
+                if (maxChars > 500) {
+                    const truncated = content.slice(0, maxChars);
+                    restoredParts.push(`### ${fp}\n\`\`\`\n${truncated}\n... (truncated)\n\`\`\``);
+                    tokenBudget = 0;
+                }
+                break;
+            }
+            restoredParts.push(`### ${fp}\n\`\`\`\n${content}\n\`\`\``);
+            tokenBudget -= estimatedTokens;
+        }
+        catch {
+            // File unreadable — skip
+        }
+    }
+    if (restoredParts.length === 0)
+        return null;
+    if (debug) {
+        console.error(`[franklin] Post-compact: restored ${restoredParts.length} files`);
+    }
+    return {
+        prompt: `[POST-COMPACT FILE RESTORATION] The following files were being actively worked on before context compaction. Their current contents are provided to restore working context:\n\n${restoredParts.join('\n\n')}`,
+    };
+}
 /**
  * Find how many recent messages to keep (don't summarize).
  * Keeps the most recent tool exchange + the last few user/assistant turns.
@@ -239,6 +349,22 @@ function formatForSummarization(messages) {
     }
     return parts.join('\n\n');
 }
+/**
+ * Strip the analysis scratchpad from compaction output and extract the summary.
+ * The model drafts in <analysis> tags (for quality), then writes the final
+ * summary in <summary> tags. We keep only the summary.
+ */
+function formatCompactSummary(raw) {
+    // Strip <analysis>...</analysis> (the drafting scratchpad)
+    let cleaned = raw.replace(/<analysis>[\s\S]*?<\/analysis>/gi, '').trim();
+    // Extract content from <summary>...</summary> if present
+    const summaryMatch = cleaned.match(/<summary>([\s\S]*?)<\/summary>/i);
+    if (summaryMatch) {
+        cleaned = summaryMatch[1].trim();
+    }
+    // If neither tag was used, the model gave us raw output — use as-is
+    return cleaned || raw.trim();
+}
 /**
  * Pick a cheaper/faster model for compaction to save cost.
  */

package/dist/agent/context.d.ts

@@ -1,11 +1,16 @@
 /**
- * Context Manager for runcode
+ * Context Manager for Franklin
  * Assembles system instructions, reads project config, injects environment info.
  */
 /**
  * Build the full system instructions array for a session.
  * Result is memoized per workingDir for the process lifetime.
  */
-export declare function assembleInstructions(workingDir: string): string[];
+export declare function assembleInstructions(workingDir: string, model?: string): string[];
+/**
+ * Model-family-specific execution guidance.
+ * Weak models get strict guardrails. Strong models get quality standards.
+ */
+export declare function getModelGuidance(model: string): string;
 /** Invalidate cache for a workingDir (call after /clear or session reset). */
-export declare function invalidateInstructionCache(workingDir: string): void;
+export declare function invalidateInstructionCache(workingDir?: string): void;