@blockrun/franklin 3.3.2 → 3.5.0

package/dist/agent/tool-guard.js

@@ -0,0 +1,324 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_WEBSEARCHES_PER_TURN = 8;
+const MAX_SIMILAR_SEARCHES_PER_TURN = 4;
+const MAX_NO_SIGNAL_SEARCHES_PER_FAMILY = 2;
+const SEARCH_FAMILY_SIMILARITY = 0.58;
+const DUPLICATE_READ_TURN_WINDOW = 1;
+const DUPLICATE_FETCH_TURN_WINDOW = 1;
+const MAX_PREVIEW_CHARS = 320;
+const SEARCH_STOPWORDS = new Set([
+    'a', 'an', 'and', 'april', 'at', 'builder', 'builders', 'com', 'developer',
+    'developers', 'for', 'from', 'in', 'latest', 'live', 'may', 'of', 'on', 'or',
+    'post', 'posts', 'recent', 'reply', 'replies', 'site', 'status', 'the', 'to',
+    'tweet', 'tweets', 'via', 'x',
+]);
+function stemToken(token) {
+    let result = token.toLowerCase();
+    if (/^\d{4}$/.test(result))
+        return '';
+    if (result.endsWith('ing') && result.length > 6)
+        result = result.slice(0, -3);
+    else if (result.endsWith('ers') && result.length > 5)
+        result = result.slice(0, -3);
+    else if (result.endsWith('er') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('ed') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('es') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('s') && result.length > 4)
+        result = result.slice(0, -1);
+    return result;
+}
+export function normalizeSearchQuery(query) {
+    const tokens = query
+        .toLowerCase()
+        .replace(/https?:\/\/\S+/g, ' ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(/\s+/)
+        .map(stemToken)
+        .filter((token) => token.length >= 2 && !SEARCH_STOPWORDS.has(token));
+    const normalized = [...new Set(tokens)].sort().join(' ');
+    return { normalized, tokens: [...new Set(tokens)] };
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersection++;
+    }
+    const union = new Set([...a, ...b]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+function summarizeOutput(output) {
+    const compact = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, 4)
+        .join('\n');
+    return compact.length > MAX_PREVIEW_CHARS
+        ? compact.slice(0, MAX_PREVIEW_CHARS - 3) + '...'
+        : compact;
+}
+function isNoSignalSearchResult(output, isError) {
+    const lower = output.toLowerCase();
+    return Boolean(isError ||
+        lower.startsWith('no results found for:') ||
+        lower.startsWith('no candidate posts found') ||
+        lower.startsWith('search timed out') ||
+        lower.startsWith('search error:') ||
+        lower.startsWith('searchx error:'));
+}
+function readKey(resolved, offset, limit) {
+    return `${resolved}::${offset ?? 1}::${limit ?? 2000}`;
+}
+function fetchKey(url, maxLength) {
+    return `${url}::${maxLength ?? 12288}`;
+}
+export class SessionToolGuard {
+    turn = 0;
+    webSearchesThisTurn = 0;
+    searchFamilies = [];
+    searchCache = new Map();
+    pendingSearches = new Map();
+    recentReads = new Map();
+    pendingReads = new Map();
+    recentFetches = new Map();
+    pendingFetches = new Map();
+    toolErrorCounts = new Map();
+    startTurn() {
+        this.turn++;
+        this.webSearchesThisTurn = 0;
+        for (const family of this.searchFamilies) {
+            family.turnSearches = 0;
+        }
+    }
+    async beforeExecute(invocation, scope) {
+        // Hard-block tools that have failed too many times this session
+        const errorCount = this.toolErrorCounts.get(invocation.name) ?? 0;
+        if (errorCount >= 3) {
+            return {
+                output: `${invocation.name} has failed ${errorCount} times this session and is now disabled. ` +
+                    'Tell the user what went wrong and suggest alternatives.',
+                isError: true,
+            };
+        }
+        switch (invocation.name) {
+            case 'WebSearch':
+            case 'SearchX':
+                return this.beforeWebSearch(invocation);
+            case 'Read':
+                return this.beforeRead(invocation, scope);
+            case 'WebFetch':
+                return this.beforeWebFetch(invocation);
+            default:
+                return null;
+        }
+    }
+    afterExecute(invocation, result) {
+        // Track per-tool error counts across the session
+        if (result.isError) {
+            this.toolErrorCounts.set(invocation.name, (this.toolErrorCounts.get(invocation.name) ?? 0) + 1);
+        }
+        switch (invocation.name) {
+            case 'WebSearch':
+            case 'SearchX':
+                this.afterWebSearch(invocation, result);
+                break;
+            case 'Read':
+                this.afterRead(invocation, result);
+                break;
+            case 'WebFetch':
+                this.afterWebFetch(invocation, result);
+                break;
+            default:
+                break;
+        }
+    }
+    cancelInvocation(invocationId) {
+        this.pendingSearches.delete(invocationId);
+        this.pendingReads.delete(invocationId);
+        this.pendingFetches.delete(invocationId);
+    }
+    beforeWebSearch(invocation) {
+        const query = String(invocation.input.query ?? '').trim();
+        const fingerprint = normalizeSearchQuery(query);
+        const normalized = fingerprint.normalized || query.toLowerCase().trim();
+        const cached = this.searchCache.get(normalized);
+        if (cached) {
+            const reason = cached.noSignal
+                ? 'That same WebSearch already returned no useful signal earlier in this session.'
+                : 'That same WebSearch already ran earlier in this session.';
+            return {
+                output: `${reason} Reuse the prior result already in context instead of searching again.\n\n` +
+                    `Previous search: ${cached.query}\n` +
+                    `Summary:\n${cached.preview}`,
+            };
+        }
+        if (this.webSearchesThisTurn >= MAX_WEBSEARCHES_PER_TURN) {
+            return {
+                output: `WebSearch budget reached for this turn (${MAX_WEBSEARCHES_PER_TURN} searches). ` +
+                    'Stop searching and synthesize the results already collected.',
+            };
+        }
+        let bestFamily = null;
+        let bestSimilarity = 0;
+        const tokenSet = new Set(fingerprint.tokens);
+        for (const family of this.searchFamilies) {
+            const similarity = jaccardSimilarity(tokenSet, family.tokens);
+            if (similarity > bestSimilarity) {
+                bestSimilarity = similarity;
+                bestFamily = family;
+            }
+        }
+        if (bestFamily && bestSimilarity >= SEARCH_FAMILY_SIMILARITY) {
+            if (bestFamily.noSignalSearches >= MAX_NO_SIGNAL_SEARCHES_PER_FAMILY) {
+                return {
+                    output: `Search stopped: ${bestFamily.noSignalSearches} similar WebSearch queries for this topic ` +
+                        `already returned empty or low-signal results.\n\n` +
+                        `Topic exemplar: ${bestFamily.exemplarQuery}\n` +
+                        'Present what you have instead of rephrasing the same search.',
+                };
+            }
+            if (bestFamily.turnSearches >= MAX_SIMILAR_SEARCHES_PER_TURN) {
+                return {
+                    output: `Search stopped: you already ran ${bestFamily.turnSearches} similar WebSearch queries ` +
+                        `for this topic in the current turn.\n\n` +
+                        `Topic exemplar: ${bestFamily.exemplarQuery}\n` +
+                        'Synthesize or switch to a materially different angle.',
+                };
+            }
+        }
+        const family = bestFamily && bestSimilarity >= SEARCH_FAMILY_SIMILARITY
+            ? bestFamily
+            : {
+                exemplarQuery: query,
+                tokens: tokenSet,
+                totalSearches: 0,
+                turnSearches: 0,
+                noSignalSearches: 0,
+            };
+        if (family === bestFamily) {
+            family.tokens = new Set([...family.tokens, ...tokenSet]);
+        }
+        else {
+            this.searchFamilies.push(family);
+        }
+        family.totalSearches++;
+        family.turnSearches++;
+        this.webSearchesThisTurn++;
+        this.pendingSearches.set(invocation.id, { normalized, family });
+        return null;
+    }
+    beforeRead(invocation, scope) {
+        const filePath = String(invocation.input.file_path ?? '');
+        if (!filePath)
+            return null;
+        const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(scope.workingDir, filePath);
+        let stat;
+        try {
+            stat = fs.statSync(resolved);
+        }
+        catch {
+            return null;
+        }
+        if (stat.isDirectory())
+            return null;
+        const offset = Number(invocation.input.offset ?? 1);
+        const limit = Number(invocation.input.limit ?? 2000);
+        const key = readKey(resolved, offset, limit);
+        const pending = [...this.pendingReads.values()].find((snapshot) => snapshot.key === key);
+        if (pending && pending.mtimeMs === stat.mtimeMs && pending.size === stat.size) {
+            return {
+                output: `Skipped duplicate Read of ${resolved}. The same file and line range is already being read ` +
+                    'in this turn, so reuse that content instead of reading it again.',
+            };
+        }
+        const previous = this.recentReads.get(key);
+        if (previous &&
+            this.turn - previous.turn <= DUPLICATE_READ_TURN_WINDOW &&
+            previous.mtimeMs === stat.mtimeMs &&
+            previous.size === stat.size) {
+            return {
+                output: `Skipped duplicate Read of ${resolved}. Same file and line range were already read ` +
+                    `${previous.turn === this.turn ? 'this turn' : 'in the previous turn'}, and the file has not changed.`,
+            };
+        }
+        this.pendingReads.set(invocation.id, {
+            key,
+            resolved,
+            offset,
+            limit,
+            turn: this.turn,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+        });
+        return null;
+    }
+    beforeWebFetch(invocation) {
+        const url = String(invocation.input.url ?? '').trim();
+        if (!url)
+            return null;
+        const maxLength = Number(invocation.input.max_length ?? 12288);
+        const key = fetchKey(url, maxLength);
+        const pending = [...this.pendingFetches.values()].find((snapshot) => snapshot.key === key);
+        if (pending) {
+            return {
+                output: `Skipped duplicate WebFetch of ${url}. The same URL is already being fetched in this turn, ` +
+                    'so reuse that result instead of fetching it again.',
+            };
+        }
+        const previous = this.recentFetches.get(key);
+        if (previous && this.turn - previous.turn <= DUPLICATE_FETCH_TURN_WINDOW) {
+            return {
+                output: `Skipped duplicate WebFetch of ${url}. The same URL was already fetched recently in this session; ` +
+                    'reuse that content already in context instead of fetching it again.',
+            };
+        }
+        this.pendingFetches.set(invocation.id, {
+            key,
+            url,
+            maxLength,
+            turn: this.turn,
+        });
+        return null;
+    }
+    afterWebSearch(invocation, result) {
+        const pending = this.pendingSearches.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingSearches.delete(invocation.id);
+        const query = String(invocation.input.query ?? '').trim();
+        const noSignal = isNoSignalSearchResult(result.output, result.isError);
+        if (noSignal) {
+            pending.family.noSignalSearches++;
+        }
+        this.searchCache.set(pending.normalized, {
+            query,
+            preview: summarizeOutput(result.output),
+            noSignal,
+        });
+    }
+    afterRead(invocation, result) {
+        const pending = this.pendingReads.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingReads.delete(invocation.id);
+        if (result.isError)
+            return;
+        this.recentReads.set(pending.key, pending);
+    }
+    afterWebFetch(invocation, result) {
+        const pending = this.pendingFetches.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingFetches.delete(invocation.id);
+        if (result.isError)
+            return;
+        this.recentFetches.set(pending.key, pending);
+    }
+}

package/dist/agent/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Core types for the runcode agent system.
+ * Core types for the Franklin agent system.
  * All type names and structures are original designs.
  */
 export type Role = 'user' | 'assistant';
@@ -45,6 +45,8 @@ export interface CapabilityHandler {
     spec: CapabilityDefinition;
     execute(input: Record<string, unknown>, ctx: ExecutionScope): Promise<CapabilityResult>;
     concurrent?: boolean;
+    /** Dynamic concurrency check — called per-invocation. Overrides `concurrent` when provided. */
+    isConcurrentSafe?: (input: Record<string, unknown>) => boolean;
 }
 export interface CapabilityResult {
     output: string;
@@ -97,6 +99,10 @@ export interface StreamUsageInfo {
     outputTokens: number;
     model: string;
     calls: number;
+    tier?: 'SIMPLE' | 'MEDIUM' | 'COMPLEX' | 'REASONING';
+    confidence?: number;
+    savings?: number;
+    contextPct?: number;
 }
 export type StreamEvent = StreamTextDelta | StreamThinkingDelta | StreamCapabilityStart | StreamCapabilityInputDelta | StreamCapabilityProgress | StreamCapabilityDone | StreamTurnDone | StreamUsageInfo;
 export interface AgentConfig {

package/dist/agent/types.js

@@ -1,5 +1,5 @@
 /**
- * Core types for the runcode agent system.
+ * Core types for the Franklin agent system.
  * All type names and structures are original designs.
  */
 export {};

package/dist/banner.js

@@ -7,32 +7,26 @@ import chalk from 'chalk';
 //   https://commons.wikimedia.org/wiki/File:BenFranklinDuplessis.jpg
 //
 // Pipeline:
-//   1. Crop the 2403×2971 original to a 1400×1400 square centred on the face
-//      (sips --cropToHeightWidth 1400 1400 --cropOffset 400 500)
+//   1. Crop the 800×989 thumb to a 500×500 square centred on the face
+//      (sips --cropToHeightWidth 500 500 --cropOffset 140 150)
 //   2. Convert via chafa:
-//      chafa --size=30x14 --symbols=block --colors=256 ben-face.jpg
+//      chafa --size=16x8 --symbols=block --colors=full ben-face.jpg
 //   3. Strip cursor visibility control codes (\x1b[?25l / \x1b[?25h)
 //   4. Paste here as hex-escaped string array (readable + diff-friendly)
 //
-// Visible dimensions: ~28 characters wide × 14 rows tall.
+// Visible dimensions: ~16 characters wide × 8 rows tall.
 //
 // Rendered best in a 256-color or truecolor terminal. Degrades gracefully
 // on ancient terminals — but those are long gone and we don't support them.
 const BEN_PORTRAIT_ROWS = [
-    '\x1b[0m\x1b[38;5;16;48;5;16m      \x1b[38;5;232m▁\x1b[38;5;235;48;5;232m▂\x1b[38;5;58;48;5;233m▄\x1b[38;5;95;48;5;234m▆\x1b[38;5;137;48;5;58m▄\x1b[38;5;173m▅\x1b[48;5;94m▅\x1b[48;5;58m▆▅\x1b[48;5;237m▄\x1b[38;5;137;48;5;234m▃\x1b[38;5;235;48;5;233m▂   \x1b[38;5;233;48;5;232m▂▅\x1b[48;5;233m     \x1b[0m',
-    '\x1b[38;5;16;48;5;16m     \x1b[38;5;235;48;5;232m▗\x1b[38;5;233;48;5;236m▘\x1b[38;5;8;48;5;239m▌\x1b[38;5;95;48;5;137m▋\x1b[38;5;137;48;5;179m▘  \x1b[38;5;179;48;5;173m▃\x1b[48;5;179m   \x1b[48;5;173m▊\x1b[38;5;58;48;5;137m▝\x1b[38;5;94;48;5;235m▖\x1b[38;5;234;48;5;233m▅▄▂  ▂▗▄▃\x1b[0m',
-    '\x1b[38;5;16;48;5;16m    \x1b[38;5;235;48;5;232m▗\x1b[38;5;236;48;5;237m▍ \x1b[38;5;58;48;5;94m▋\x1b[38;5;95;48;5;173m▌\x1b[48;5;179m \x1b[38;5;179;48;5;215m▍\x1b[48;5;221m▔\x1b[38;5;222;48;5;180m▍\x1b[48;5;179m  \x1b[38;5;173m▕\x1b[38;5;179;48;5;173m▅\x1b[38;5;137m▕\x1b[38;5;95;48;5;58m▍\x1b[38;5;58;48;5;235m▖\x1b[38;5;235;48;5;234m▖▃▄     \x1b[0m',
-    '\x1b[38;5;16;48;5;16m   \x1b[38;5;233m▗\x1b[48;5;235m▏\x1b[38;5;237;48;5;238m▊\x1b[38;5;238;48;5;236m▌\x1b[38;5;236;48;5;58m▖\x1b[38;5;95;48;5;179m▌ \x1b[38;5;137m▗\x1b[38;5;94m▄\x1b[38;5;58m▄\x1b[38;5;94m▄\x1b[38;5;137m▖\x1b[38;5;173m▗\x1b[38;5;131m▗\x1b[38;5;58;48;5;137m▃\x1b[38;5;131;48;5;58m▘\x1b[38;5;234m▕\x1b[48;5;236m▖\x1b[38;5;236;48;5;235m▃    \x1b[38;5;234m▝\x1b[38;5;235;48;5;234m▃\x1b[0m',
-    '\x1b[38;5;16;48;5;16m  \x1b[38;5;235;48;5;232m▂\x1b[38;5;236;48;5;234m▄\x1b[38;5;237;48;5;236m▗\x1b[38;5;8;48;5;239m▖\x1b[38;5;240;48;5;8m▎\x1b[38;5;94;48;5;236m▕\x1b[38;5;137;48;5;179m▍ \x1b[38;5;94;48;5;137m▝\x1b[38;5;173;48;5;94m▂\x1b[38;5;137;48;5;58m▂\x1b[48;5;94m▃\x1b[48;5;179m▘\x1b[38;5;173m▝\x1b[38;5;137;48;5;235m▍\x1b[38;5;94;48;5;236m▝\x1b[38;5;235;48;5;94m▖\x1b[38;5;52;48;5;58m▖\x1b[38;5;235;48;5;233m▝\x1b[48;5;236m▁\x1b[48;5;235m      \x1b[0m',
-    '\x1b[38;5;232;48;5;16m▗\x1b[38;5;233;48;5;236m▌\x1b[38;5;95;48;5;239m▅\x1b[48;5;240m▃\x1b[38;5;94;48;5;238m▖\x1b[38;5;240;48;5;8m▝\x1b[38;5;95;48;5;236m▘\x1b[38;5;236;48;5;95m▘\x1b[38;5;173;48;5;179m▏ \x1b[38;5;215m▄ \x1b[38;5;179;48;5;137m▅\x1b[38;5;137;48;5;179m▘\x1b[38;5;216m▘\x1b[38;5;179;48;5;216m▃\x1b[48;5;94m▌\x1b[38;5;94;48;5;131m▘\x1b[38;5;95;48;5;94m▋\x1b[38;5;94;48;5;52m▃\x1b[38;5;52;48;5;233m▎\x1b[38;5;233;48;5;235m▅\x1b[38;5;234m▂     \x1b[0m',
-    '\x1b[38;5;233;48;5;232m▕\x1b[38;5;234;48;5;236m▘\x1b[38;5;8;48;5;95m▌ \x1b[38;5;236m▃\x1b[38;5;58;48;5;234m▘\x1b[38;5;94m▝\x1b[48;5;137m▎\x1b[38;5;179;48;5;173m▍\x1b[38;5;173;48;5;179m▌▆▖▃▞\x1b[38;5;94;48;5;173m▗\x1b[48;5;179m▄\x1b[38;5;179;48;5;58m▘\x1b[38;5;94;48;5;52m▝\x1b[38;5;130;48;5;131m▃\x1b[38;5;94;48;5;58m▍\x1b[38;5;52;48;5;232m▎\x1b[38;5;232;48;5;233m▌\x1b[38;5;233;48;5;234m▏\x1b[38;5;234;48;5;235m▎\x1b[38;5;236m▌▅▄ \x1b[0m',
-    '\x1b[38;5;232;48;5;235m▋\x1b[38;5;58;48;5;236m▝\x1b[48;5;58m \x1b[38;5;239;48;5;94m▅\x1b[38;5;237;48;5;235m▂\x1b[38;5;235;48;5;233m▂\x1b[38;5;234;48;5;94m▄\x1b[38;5;94;48;5;137m▖\x1b[48;5;173m \x1b[38;5;173;48;5;179m▃  \x1b[38;5;137m▂▃▂\x1b[38;5;131;48;5;137m▃\x1b[38;5;58;48;5;131m▝\x1b[38;5;94;48;5;52m▅\x1b[48;5;94m \x1b[48;5;58m▍\x1b[38;5;235;48;5;232m▎\x1b[38;5;232;48;5;233m▋\x1b[38;5;233;48;5;234m▍\x1b[38;5;235;48;5;236m▏  \x1b[38;5;236;48;5;235m▎ \x1b[0m',
-    '\x1b[38;5;234;48;5;235m▏\x1b[38;5;236;48;5;237m▋\x1b[38;5;237;48;5;8m▃\x1b[38;5;235;48;5;238m▗\x1b[38;5;237m▖\x1b[38;5;58;48;5;234m▌\x1b[38;5;234;48;5;233m▎\x1b[38;5;236;48;5;137m▎\x1b[38;5;137;48;5;173m▄ \x1b[38;5;173;48;5;179m▄▃ \x1b[38;5;179;48;5;215m▅\x1b[38;5;173;48;5;179m▄\x1b[38;5;179;48;5;137m▘\x1b[38;5;137;48;5;131m▌\x1b[48;5;94m \x1b[38;5;58m▗\x1b[38;5;233;48;5;58m▗\x1b[48;5;233m  \x1b[38;5;234;48;5;236m▘ \x1b[38;5;236;48;5;235m▃▞\x1b[38;5;235;48;5;236m▄\x1b[48;5;235m \x1b[0m',
-    '\x1b[38;5;234;48;5;235m▏▆\x1b[38;5;235;48;5;237m▌\x1b[38;5;236m▝\x1b[38;5;237;48;5;234m▍\x1b[38;5;234;48;5;233m▖\x1b[38;5;240;48;5;234m▗\x1b[38;5;101;48;5;186m▌\x1b[38;5;137m▝\x1b[48;5;137m   \x1b[48;5;173m▆▄▃\x1b[38;5;131m▂\x1b[38;5;130;48;5;137m▂\x1b[38;5;58;48;5;94m▃\x1b[48;5;58m \x1b[38;5;234;48;5;233m▏\x1b[38;5;235;48;5;234m▅\x1b[48;5;236m▌   ▝ \x1b[48;5;235m \x1b[0m',
-    '\x1b[38;5;234;48;5;233m▕\x1b[38;5;239;48;5;235m▂\x1b[38;5;95m▃\x1b[48;5;237m▄\x1b[48;5;236m▄\x1b[48;5;235m▄\x1b[38;5;236;48;5;240m▘\x1b[38;5;101;48;5;95m▕\x1b[48;5;186m▖\x1b[38;5;179;48;5;229m▝\x1b[38;5;223;48;5;137m▃\x1b[38;5;137;48;5;131m▁\x1b[38;5;95m▅\x1b[38;5;94m▂\x1b[48;5;94m \x1b[38;5;58m▗\x1b[38;5;94;48;5;58m▔\x1b[38;5;236m▁ \x1b[48;5;235m▆\x1b[38;5;235;48;5;236m▍\x1b[38;5;236;48;5;235m▆\x1b[48;5;236m    \x1b[38;5;235m▅\x1b[48;5;235m \x1b[0m',
-    '\x1b[38;5;237;48;5;95m▔       \x1b[38;5;137;48;5;101m▝\x1b[48;5;187m▅\x1b[38;5;180;48;5;229m▂\x1b[38;5;143;48;5;222m▔\x1b[38;5;186;48;5;58m▅\x1b[38;5;179m▂\x1b[38;5;95m▁\x1b[38;5;235m▂\x1b[38;5;236m▄\x1b[48;5;233m▌\x1b[38;5;235m▔\x1b[38;5;233;48;5;236m▅\x1b[38;5;234m▃\x1b[38;5;235m▁    ▔\x1b[48;5;235m \x1b[0m',
-    '\x1b[38;5;101;48;5;137m▔\x1b[38;5;95;48;5;101m▄▔\x1b[38;5;101;48;5;95m▄  ▗ \x1b[38;5;240m▖\x1b[38;5;95;48;5;101m▘\x1b[38;5;137m▔\x1b[48;5;222m▅\x1b[48;5;186m▃\x1b[48;5;179m▂\x1b[38;5;101;48;5;95m▌\x1b[48;5;58m \x1b[38;5;238;48;5;236m▁\x1b[38;5;180;48;5;234m▃\x1b[48;5;235m▄\x1b[38;5;179;48;5;234m▃\x1b[38;5;95m▁\x1b[38;5;234;48;5;235m▊\x1b[48;5;236m▆\x1b[38;5;235m▃\x1b[38;5;234m▂\x1b[38;5;235m▁ \x1b[38;5;236;48;5;235m▎\x1b[0m',
-    '\x1b[38;5;137;48;5;137m \x1b[48;5;95m▄ \x1b[38;5;95;48;5;101m▖\x1b[48;5;137m▝\x1b[48;5;95m \x1b[38;5;101m▅\x1b[48;5;239m▋\x1b[48;5;95m \x1b[38;5;95;48;5;137m▋\x1b[38;5;101;48;5;95m▍\x1b[38;5;95;48;5;101m▖\x1b[38;5;101;48;5;95m▆\x1b[38;5;239m▗\x1b[38;5;101m▄ \x1b[38;5;95;48;5;137m▅\x1b[38;5;137;48;5;180m▅\x1b[38;5;180;48;5;186m▃\x1b[48;5;143m▆\x1b[38;5;95m▔\x1b[38;5;143;48;5;235m▖\x1b[48;5;234m \x1b[38;5;235m▆\x1b[38;5;234;48;5;235m▝\x1b[38;5;235;48;5;234m▞\x1b[38;5;234;48;5;235m▄ \x1b[0m',
+    '\x1b[0m\x1b[38;2;7;0;0;48;2;8;0;0m▔ \x1b[38;2;9;1;0m▂\x1b[38;2;56;36;15;48;2;11;2;0m▗\x1b[38;2;100;73;36;48;2;31;16;6m▅\x1b[38;2;189;141;75;48;2;117;87;43m▅\x1b[38;2;217;162;85;48;2;152;111;51m▆\x1b[38;2;164;122;64;48;2;215;158;85m▔\x1b[38;2;124;90;46;48;2;217;160;93m▔\x1b[38;2;185;136;75;48;2;77;48;20m▅\x1b[38;2;100;61;24;48;2;39;18;4m▖\x1b[38;2;48;26;9;48;2;32;13;3m▃\x1b[38;2;39;18;4;48;2;30;11;2m▄\x1b[38;2;38;17;4;48;2;32;13;3m▄\x1b[38;2;40;20;5;48;2;35;15;2m▃\x1b[38;2;41;21;5;48;2;36;16;3m▂\x1b[0m',
+    '\x1b[7m\x1b[38;2;8;0;0m \x1b[0m\x1b[38;2;0;0;0;48;2;8;0;0m \x1b[38;2;13;2;1;48;2;45;26;10m▊\x1b[38;2;61;40;17;48;2;87;63;31m▎\x1b[38;2;88;61;29;48;2;134;94;42m▋\x1b[38;2;182;132;66;48;2;223;172;93m▏\x1b[38;2;140;91;38;48;2;233;193;106m▂\x1b[38;2;135;82;35;48;2;229;178;106m▂\x1b[38;2;201;145;78;48;2;223;166;95m▂\x1b[38;2;133;88;46;48;2;198;148;86m▁\x1b[38;2;144;96;47;48;2;96;57;21m▍\x1b[38;2;66;42;15;48;2;58;33;11m▗\x1b[38;2;59;36;13;48;2;47;25;9m▆\x1b[38;2;57;35;11;48;2;46;24;7m▅\x1b[38;2;58;36;11;48;2;50;29;8m▖\x1b[38;2;53;32;8;48;2;48;26;7m▃\x1b[0m',
+    '\x1b[38;2;12;3;3;48;2;9;0;0m▁\x1b[38;2;102;76;40;48;2;19;8;4m▗\x1b[38;2;110;83;45;48;2;56;35;15m▄\x1b[38;2;91;67;37;48;2;105;79;45m▌\x1b[38;2;96;64;31;48;2;186;135;70m▊\x1b[38;2;226;169;101;48;2;217;162;91m▗\x1b[38;2;216;159;89;48;2;144;93;44m▅\x1b[38;2;195;145;83;48;2;112;62;24m▅\x1b[38;2;233;178;110;48;2;206;151;81m▆\x1b[38;2;207;155;92;48;2;105;61;30m▎\x1b[38;2;145;94;46;48;2;94;50;19m▖\x1b[38;2;90;48;17;48;2;52;26;8m▎\x1b[38;2;59;33;9;48;2;64;40;14m▖\x1b[38;2;63;39;13;48;2;65;41;13m▊\x1b[38;2;58;36;11;48;2;64;40;14m▝\x1b[38;2;60;38;13;48;2;57;35;10m▍\x1b[0m',
+    '\x1b[38;2;37;22;12;48;2;11;2;2m▕\x1b[38;2;52;32;16;48;2;94;67;32m▘\x1b[38;2;77;53;21;48;2;125;96;52m▗\x1b[38;2;44;15;6;48;2;83;48;21m▞\x1b[38;2;122;73;33;48;2;195;138;72m▍\x1b[38;2;209;149;77;48;2;223;160;89m▋\x1b[38;2;228;157;84;48;2;234;173;98m▆\x1b[38;2;207;140;80;48;2;225;167;96m▝\x1b[38;2;213;151;88;48;2;193;135;79m▏\x1b[38;2;164;111;60;48;2;104;54;21m▍\x1b[38;2;175;110;52;48;2;136;78;32m▘\x1b[38;2;93;47;15;48;2;26;5;2m▎\x1b[38;2;39;13;4;48;2;54;28;8m▍\x1b[38;2;63;40;13;48;2;67;44;16m▔\x1b[38;2;68;44;15;48;2;65;41;16m▊\x1b[38;2;60;36;11;48;2;63;39;14m▝\x1b[0m',
+    '\x1b[38;2;12;1;0;48;2;55;33;13m▌\x1b[38;2;92;63;32;48;2;68;43;17m▝\x1b[38;2;75;51;24;48;2;93;65;34m▗\x1b[38;2;88;61;30;48;2;42;18;8m▘\x1b[38;2;62;35;18;48;2;191;150;83m▍\x1b[38;2;186;140;75;48;2;194;138;63m▁\x1b[38;2;189;130;61;48;2;219;157;79m▄\x1b[38;2;191;132;70;48;2;217;159;87m▂\x1b[38;2;179;105;60;48;2;207;146;83m▔\x1b[38;2;171;106;51;48;2;135;79;32m▋\x1b[38;2;64;30;8;48;2;120;69;27m▗\x1b[38;2;56;26;8;48;2;39;13;5m▂\x1b[38;2;44;18;7;48;2;72;44;16m▘\x1b[38;2;72;47;18;48;2;69;44;14m▖\x1b[38;2;70;46;14;48;2;68;44;14m▁\x1b[38;2;65;41;12;48;2;65;41;14m▘\x1b[0m',
+    '\x1b[38;2;77;56;35;48;2;22;8;3m▂\x1b[38;2;126;100;69;48;2;59;36;15m▃\x1b[38;2;131;105;70;48;2;80;54;27m▄\x1b[38;2;128;103;68;48;2;57;33;14m▄\x1b[38;2;191;174;117;48;2;125;103;69m▝\x1b[38;2;191;164;108;48;2;236;227;160m▞\x1b[38;2;220;202;137;48;2;173;123;63m▃\x1b[38;2;130;85;43;48;2;164;111;58m▄\x1b[38;2;117;68;26;48;2;185;116;58m▆\x1b[38;2;135;80;33;48;2;94;52;15m▘\x1b[38;2;51;28;9;48;2;80;50;16m▂\x1b[38;2;62;33;9;48;2;76;46;14m▘\x1b[38;2;75;50;16;48;2;74;47;15m▗\x1b[38;2;71;46;14;48;2;72;47;15m▝\x1b[38;2;73;48;16;48;2;69;44;14m▏\x1b[38;2;65;41;11;48;2;66;41;15m▆\x1b[0m',
+    '\x1b[38;2;125;101;70;48;2;159;129;87m▔\x1b[38;2;145;114;71;48;2;124;100;70m▆\x1b[38;2;152;123;81;48;2;121;100;69m▃\x1b[38;2;117;95;60;48;2;129;106;70m▖\x1b[38;2;115;91;61;48;2;131;105;69m▗\x1b[38;2;166;145;103;48;2;140;113;71m▔\x1b[38;2;162;135;87;48;2;231;217;147m▅\x1b[38;2;133;107;71;48;2;199;171;110m▂\x1b[38;2;131;100;59;48;2;107;75;37m▍\x1b[38;2;166;139;88;48;2;67;40;14m▃\x1b[38;2;204;179;121;48;2;39;19;8m▄\x1b[38;2;137;112;73;48;2;52;28;10m▖\x1b[38;2;54;32;10;48;2;76;49;16m▅\x1b[38;2;56;33;9;48;2;74;48;15m▃\x1b[38;2;60;37;10;48;2;70;47;14m▁\x1b[38;2;66;43;12;48;2;64;40;11m▅\x1b[0m',
+    '\x1b[38;2;157;128;85;48;2;167;138;98m▝\x1b[38;2;141;111;71;48;2;166;136;98m▝\x1b[38;2;149;119;83;48;2;126;96;60m▞\x1b[38;2;157;129;93;48;2;139;113;81m▅\x1b[38;2;144;117;79;48;2;117;92;58m▋\x1b[38;2;130;102;62;48;2;169;138;87m▋\x1b[38;2;171;141;87;48;2;143;117;77m▖\x1b[38;2;144;117;79;48;2;122;96;63m▊\x1b[38;2;132;105;68;48;2;144;117;82m▖\x1b[38;2;153;127;92;48;2;140;115;83m▞\x1b[38;2;134;108;71;48;2;217;193;135m▅\x1b[38;2;176;150;98;48;2;129;105;66m▋\x1b[38;2;118;94;61;48;2;54;32;14m▂\x1b[38;2;44;23;8;48;2;59;37;13m▃\x1b[38;2;62;41;16;48;2;48;26;9m▖\x1b[38;2;46;24;6;48;2;66;42;15m▖\x1b[0m',
 ];
 // ─── FRANKLIN text banner (gold → emerald gradient) ────────────────────────
 //
@@ -69,9 +63,9 @@ function interpolateHex(start, end, t) {
 }
 // ─── Banner layout ─────────────────────────────────────────────────────────
 // Minimum terminal width to show the side-by-side portrait + text layout.
-// The portrait is ~28 chars, the FRANKLIN text is ~65 chars, plus a 3-char
-// gap = 96 chars. We add a small margin so 100 cols is the threshold.
-const MIN_WIDTH_FOR_PORTRAIT = 100;
+// The portrait is ~16 chars, the FRANKLIN text is ~65 chars, plus a 3-char
+// gap = 84 chars. We round up to 85 cols as the threshold.
+const MIN_WIDTH_FOR_PORTRAIT = 85;
 /**
  * Pad a line to an exact visual width, ignoring ANSI escape codes when
  * measuring. Used to align the portrait's right edge before the text block.
@@ -99,28 +93,21 @@ export function printBanner(version) {
 }
 /**
  * Full layout: Ben Franklin portrait on the left, FRANKLIN text block on the
- * right. Portrait is 14 rows × ~28 chars, text is 6 rows — text is vertically
- * centred inside the portrait with 4 rows of padding above and 4 below,
- * tagline sitting right under the FRANKLIN block.
+ * right. Portrait is 8 rows × ~16 chars, text is 6 rows — text is vertically
+ * centred inside the portrait with 1 row of padding above.
  *
- *   [portrait row  1]                (empty)
- *   [portrait row  2]                (empty)
- *   [portrait row  3]                (empty)
- *   [portrait row  4]                (empty)
- *   [portrait row  5]   ███████╗██████╗  █████╗ ...
- *   [portrait row  6]   ██╔════╝██╔══██╗██╔══██╗...
- *   [portrait row  7]   █████╗  ██████╔╝███████║...
- *   [portrait row  8]   ██╔══╝  ██╔══██╗██╔══██║...
- *   [portrait row  9]   ██║     ██║  ██║██║  ██║...
- *   [portrait row 10]   ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝...
- *   [portrait row 11]   blockrun.ai · The AI agent with a wallet · vX
- *   [portrait row 12]                (empty)
- *   [portrait row 13]                (empty)
- *   [portrait row 14]                (empty)
+ *   [portrait row 1]                (empty)
+ *   [portrait row 2]   ███████╗██████╗  █████╗ ...
+ *   [portrait row 3]   ██╔════╝██╔══██╗██╔══██╗...
+ *   [portrait row 4]   █████╗  ██████╔╝███████║...
+ *   [portrait row 5]   ██╔══╝  ██╔══██╗██╔══██║...
+ *   [portrait row 6]   ██║     ██║  ██║██║  ██║...
+ *   [portrait row 7]   ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝...
+ *   [portrait row 8]   blockrun.ai · The AI agent with a wallet · vX
  */
 function printSideBySide(version) {
-    const TEXT_TOP_OFFSET = 4; // rows of portrait above the text
-    const PORTRAIT_WIDTH = 29; // columns (char width) of the portrait + 1 pad
+    const TEXT_TOP_OFFSET = 1; // rows of portrait above the text
+    const PORTRAIT_WIDTH = 17; // columns (char width) of the portrait + 1 pad
     const GAP = '  '; // gap between portrait and text
     const portraitRows = BEN_PORTRAIT_ROWS;
     const textRows = FRANKLIN_ART.length;

package/dist/brain/extract.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Franklin Brain — entity extraction from session traces.
+ * Uses cheap model to detect people, projects, companies from conversation.
+ */
+import { ModelClient } from '../agent/llm.js';
+import type { Dialogue } from '../agent/types.js';
+/**
+ * Extract entities from a session and store in the brain.
+ * Fire-and-forget — caller should not await.
+ */
+export declare function extractBrainEntities(history: Dialogue[], sessionId: string, client: ModelClient): Promise<number>;

package/dist/brain/extract.js

@@ -0,0 +1,154 @@
+/**
+ * Franklin Brain — entity extraction from session traces.
+ * Uses cheap model to detect people, projects, companies from conversation.
+ */
+import { loadEntities, saveEntities, upsertEntity, addObservation, upsertRelation, } from './store.js';
+const EXTRACTION_MODELS = [
+    'google/gemini-2.5-flash-lite',
+    'google/gemini-2.5-flash',
+    'nvidia/nemotron-super-49b',
+];
+const VALID_TYPES = new Set(['person', 'project', 'company', 'product', 'concept']);
+const BRAIN_PROMPT = `You are analyzing a conversation between a user and an AI agent. Extract entities (people, projects, companies, products, concepts) mentioned in the conversation.
+
+For each entity, provide:
+- name: canonical name (e.g. "Garry Tan" not "garry" or "Garry")
+- type: person | project | company | product | concept
+- aliases: other names used for the same entity (handles, abbreviations)
+- observations: 1-3 facts learned about this entity from the conversation
+
+Also extract relationships between entities:
+- from: entity name
+- to: entity name
+- type: founded | works_on | partnered_with | uses | mentioned | replied_to | depends_on
+
+Rules:
+- Only extract entities with CLEAR evidence in the conversation.
+- Do NOT extract the AI agent itself or generic concepts ("TypeScript", "JavaScript").
+- DO extract specific people, specific projects, specific companies, specific products.
+- Observations should be concrete facts, not vague descriptions.
+- If no entities are found, return empty arrays.
+
+Respond with ONLY a JSON object (no markdown fences):
+{"entities":[{"name":"...","type":"person","aliases":["@handle"],"observations":["Founded X in 2025"]}],"relations":[{"from":"Person","to":"Project","type":"founded"}]}`;
+function condenseForBrain(history) {
+    const parts = [];
+    let chars = 0;
+    for (const msg of history) {
+        if (chars >= 3000)
+            break;
+        let text = '';
+        if (typeof msg.content === 'string') {
+            text = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            text = msg.content
+                .filter(p => p.type === 'text')
+                .map(p => p.text ?? '')
+                .join('\n');
+        }
+        if (!text.trim())
+            continue;
+        if (text.length > 400)
+            text = text.slice(0, 400) + '…';
+        const role = msg.role === 'user' ? 'User' : 'Assistant';
+        const line = `${role}: ${text}`;
+        parts.push(line);
+        chars += line.length;
+    }
+    return parts.join('\n\n');
+}
+function parseExtraction(raw) {
+    let cleaned = raw.replace(/```json\s*/gi, '').replace(/```\s*/g, '').trim();
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start === -1 || end === -1)
+        return { entities: [], relations: [] };
+    cleaned = cleaned.slice(start, end + 1);
+    try {
+        const parsed = JSON.parse(cleaned);
+        const entities = (parsed.entities || [])
+            .filter((e) => typeof e.name === 'string' && e.name.length > 1 &&
+            typeof e.type === 'string' && VALID_TYPES.has(e.type))
+            .map((e) => ({
+            name: e.name.slice(0, 100),
+            type: e.type,
+            aliases: Array.isArray(e.aliases) ? e.aliases.slice(0, 5) : [],
+            observations: Array.isArray(e.observations)
+                ? e.observations.filter(o => typeof o === 'string' && o.length > 5).slice(0, 5)
+                : [],
+        }));
+        const relations = (parsed.relations || [])
+            .filter((r) => typeof r.from === 'string' && typeof r.to === 'string' && typeof r.type === 'string')
+            .map((r) => ({
+            from: r.from,
+            to: r.to,
+            type: r.type.slice(0, 30),
+        }));
+        return { entities, relations };
+    }
+    catch {
+        return { entities: [], relations: [] };
+    }
+}
+/**
+ * Extract entities from a session and store in the brain.
+ * Fire-and-forget — caller should not await.
+ */
+export async function extractBrainEntities(history, sessionId, client) {
+    if (history.length < 4)
+        return 0;
+    const condensed = condenseForBrain(history);
+    if (condensed.length < 80)
+        return 0;
+    let result = null;
+    for (const model of EXTRACTION_MODELS) {
+        try {
+            const response = await client.complete({
+                model,
+                messages: [{ role: 'user', content: condensed }],
+                system: BRAIN_PROMPT,
+                max_tokens: 1500,
+                temperature: 0.2,
+            });
+            const text = response.content
+                .filter(p => p.type === 'text')
+                .map(p => p.text ?? '')
+                .join('');
+            result = parseExtraction(text);
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!result || (result.entities.length === 0 && result.relations.length === 0))
+        return 0;
+    // Store entities + observations
+    const entities = loadEntities();
+    const nameToId = new Map();
+    for (const extracted of result.entities) {
+        const entityId = upsertEntity(entities, extracted.name, extracted.type, extracted.aliases);
+        nameToId.set(extracted.name.toLowerCase(), entityId);
+        for (const obs of extracted.observations) {
+            addObservation(entityId, obs, sessionId);
+        }
+    }
+    saveEntities(entities);
+    // Store relations
+    for (const rel of result.relations) {
+        const fromId = nameToId.get(rel.from.toLowerCase()) ||
+            findEntityIdByName(entities, rel.from);
+        const toId = nameToId.get(rel.to.toLowerCase()) ||
+            findEntityIdByName(entities, rel.to);
+        if (fromId && toId) {
+            upsertRelation(fromId, toId, rel.type);
+        }
+    }
+    return result.entities.length;
+}
+function findEntityIdByName(entities, name) {
+    const lower = name.toLowerCase();
+    return entities.find(e => e.name.toLowerCase() === lower ||
+        e.aliases.some(a => a.toLowerCase() === lower))?.id;
+}