@blockrun/franklin 3.8.9 → 3.8.11

package/dist/agent/error-classifier.js

@@ -96,6 +96,7 @@ export function classifyAgentError(message) {
         'workers are busy',
         'all workers are busy',
         'server busy',
+        'high demand',
         'capacity',
     ])) {
         return {

package/dist/agent/llm.d.ts

@@ -27,6 +27,13 @@ export interface LLMClientOptions {
     chain: Chain;
     debug?: boolean;
 }
+/**
+ * Extract the most human-readable message from an error body.
+ * Some gateways wrap provider errors multiple times, e.g.
+ * `{"error":{"message":"{\"error\":{\"message\":\"...\"}}"}}`.
+ * Peel those layers so the UI doesn't show raw nested JSON.
+ */
+export declare function extractApiErrorMessage(errorBody: string): string;
 /**
  * Apply Anthropic prompt caching using the `system_and_3` strategy.
  * Pattern from nousresearch/hermes-agent `agent/prompt_caching.py`.

package/dist/agent/llm.js

@@ -6,6 +6,53 @@
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { USER_AGENT } from '../config.js';
 import { ThinkTagStripper } from './think-tag-stripper.js';
+/**
+ * Extract the most human-readable message from an error body.
+ * Some gateways wrap provider errors multiple times, e.g.
+ * `{"error":{"message":"{\"error\":{\"message\":\"...\"}}"}}`.
+ * Peel those layers so the UI doesn't show raw nested JSON.
+ */
+export function extractApiErrorMessage(errorBody) {
+    const visited = new Set();
+    const walk = (value, depth = 0) => {
+        // Some providers wrap the real message under error.message as a JSON
+        // string, which adds another object/string hop. Allow a few layers of
+        // nesting without risking runaway recursion.
+        if (depth > 8 || visited.has(value))
+            return null;
+        if (value && (typeof value === 'object' || typeof value === 'string')) {
+            visited.add(value);
+        }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed) {
+                try {
+                    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+                        const parsed = JSON.parse(trimmed);
+                        const nested = walk(parsed, depth + 1);
+                        if (nested)
+                            return nested;
+                    }
+                }
+                catch { /* plain string — use as-is below */ }
+            }
+            return trimmed || null;
+        }
+        if (!value || typeof value !== 'object')
+            return null;
+        const obj = value;
+        for (const key of ['error', 'message', 'detail', 'reason']) {
+            if (key in obj) {
+                const nested = walk(obj[key], depth + 1);
+                if (nested)
+                    return nested;
+            }
+        }
+        return null;
+    };
+    const extracted = walk(errorBody) ?? errorBody;
+    return extracted.replace(/\s+/g, ' ').trim();
+}
 // ─── Anthropic Prompt Caching ─────────────────────────────────────────────
 /**
  * Apply Anthropic prompt caching using the `system_and_3` strategy.
@@ -265,13 +312,7 @@ export class ModelClient {
         }
         if (!response.ok) {
             const errorBody = await response.text().catch(() => 'unknown error');
-            // Extract human-readable message from JSON error bodies ({"error":{"message":"..."}})
-            let message = errorBody;
-            try {
-                const parsed = JSON.parse(errorBody);
-                message = parsed?.error?.message || parsed?.message || errorBody;
-            }
-            catch { /* not JSON — use raw text */ }
+            const message = extractApiErrorMessage(errorBody);
             yield {
                 kind: 'error',
                 payload: { status: response.status, message },

package/dist/agent/loop.js

@@ -346,6 +346,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         activeTools.add(activateToolCap.spec.name);
     const allToolDefs = [...capabilityMap.values()].map(c => c.spec);
     const buildCallToolDefs = () => dynamicTools ? allToolDefs.filter(t => activeTools.has(t.name)) : allToolDefs;
+    const buildActiveCapabilityMap = () => dynamicTools
+        ? new Map([...capabilityMap.entries()].filter(([name]) => activeTools.has(name)))
+        : capabilityMap;
     const maxTurns = config.maxTurns ?? 15;
     const workDir = config.workingDir ?? process.cwd();
     const permissions = new PermissionManager(config.permissionMode ?? 'default', config.permissionPromptFn);
@@ -649,8 +652,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             let usage;
             let stopReason;
             // Create streaming executor for concurrent tool execution
+            const activeCapabilityMap = buildActiveCapabilityMap();
             const streamExec = new StreamingExecutor({
-                handlers: capabilityMap,
+                handlers: activeCapabilityMap,
                 scope: {
                     workingDir: workDir,
                     abortSignal: abort.signal,

package/dist/banner.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { kickoffVersionCheck, getAvailableUpdate } from './version-check.js';
 // ─── Ben Franklin portrait ─────────────────────────────────────────────────
 //
 // Generated once, at build time, from the Joseph Duplessis 1785 oil painting
@@ -82,6 +83,38 @@ function padVisible(s, targetWidth) {
     return s + '\x1b[0m' + ' '.repeat(targetWidth - current);
 }
 export function printBanner(version) {
+    const style = process.env.FRANKLIN_BANNER?.toLowerCase();
+    if (style === 'full' || style === 'legacy') {
+        printLegacyBanner(version);
+    }
+    else {
+        printCompactBanner(version);
+    }
+    // Kick off a background refresh for *next* startup, and print a hint now
+    // if the cache already knows about a newer version. All wrapped in
+    // try/catch because a banner should never be the reason startup breaks.
+    try {
+        kickoffVersionCheck();
+        const update = getAvailableUpdate();
+        if (update) {
+            console.log(chalk.yellow('⟳ ') +
+                chalk.bold(`Franklin ${update.latest}`) +
+                chalk.dim(` available — you have ${update.current}`));
+            console.log(chalk.dim('  Run: ') +
+                chalk.bold('npm install -g @blockrun/franklin@latest'));
+            console.log('');
+        }
+    }
+    catch { /* version-check is best-effort; never block startup */ }
+}
+function printCompactBanner(version) {
+    const title = chalk.bold.hex(GOLD_START)('FRANKLIN');
+    const meta = chalk.dim(`  ·  blockrun.ai  ·  v${version}`);
+    console.log(`${title}${meta}`);
+    console.log(chalk.dim('The AI agent with a wallet'));
+    console.log('');
+}
+function printLegacyBanner(version) {
     const termWidth = process.stdout.columns ?? 80;
     const useSideBySide = termWidth >= MIN_WIDTH_FOR_PORTRAIT;
     if (useSideBySide) {

package/dist/commands/doctor.js

@@ -17,6 +17,7 @@ import os from 'node:os';
 import { setupAgentWallet, setupAgentSolanaWallet, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION, BLOCKRUN_DIR } from '../config.js';
 import { isTelemetryEnabled, readAllRecords } from '../telemetry/store.js';
+import { getAvailableUpdate, kickoffVersionCheck } from '../version-check.js';
 async function runChecks() {
     const out = [];
     // ── 1. Runtime ────────────────────────────────────────────────────
@@ -29,10 +30,17 @@ async function runChecks() {
         remedy: nodeMajor >= 20 ? undefined : 'Upgrade Node.js: https://nodejs.org',
     });
     // ── 2. Franklin version ───────────────────────────────────────────
+    // Kick the daily cache refresh so subsequent doctor runs carry fresh
+    // data. Current run uses whatever's already cached.
+    kickoffVersionCheck();
+    const update = getAvailableUpdate();
     out.push({
         name: 'Franklin',
-        status: 'ok',
-        detail: `v${VERSION}`,
+        status: update ? 'warn' : 'ok',
+        detail: update
+            ? `v${VERSION} — update available: v${update.latest}`
+            : `v${VERSION}`,
+        remedy: update ? 'npm install -g @blockrun/franklin@latest' : undefined,
     });
     // ── 3. BLOCKRUN_DIR writable ──────────────────────────────────────
     try {

package/dist/index.js

@@ -265,7 +265,7 @@ if (firstArg === 'solana' || firstArg === 'base') {
     saveChain(firstArg);
     const startOpts = parseStartFlags(args, 1);
     await startCommand(startOpts);
-    process.exit(0);
+    process.exit(process.exitCode ?? 0);
 }
 else if (!firstArg || firstArg.startsWith('-')) {
     if (hasAnyFlag(args, HELP_FLAGS) && hasStartOnlyFlag(args)) {
@@ -281,7 +281,7 @@ else if (!firstArg || firstArg.startsWith('-')) {
     // No subcommand or only flags — treat as 'start' with flags
     const startOpts = parseStartFlags(args, 0);
     await startCommand(startOpts);
-    process.exit(0);
+    process.exit(process.exitCode ?? 0);
 }
 else {
     program.parse();

package/dist/ui/app.js

@@ -39,12 +39,16 @@ function useTerminalSize() {
 }
 function InputBox({ input, setInput, onSubmit, model, balance, sessionCost, queued, queuedCount, focused, busy, contextPct, vimMode, onVimModeChange }) {
     const { cols } = useTerminalSize();
+    // Avoid drawing right up to the terminal edge. Several terminals auto-wrap
+    // a full-width border glyph onto the next row, which leaves "ghost" top
+    // borders behind on re-render after errors / status changes.
+    const boxWidth = Math.max(20, cols - 2);
     const placeholder = busy
         ? (queued
             ? `⏎ ${queuedCount ?? 1} queued: ${queued.slice(0, 40)}`
             : 'Working...')
         : 'Type a message...';
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { borderStyle: "round", borderDimColor: true, paddingX: 1, width: cols, children: [busy && !input ? _jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " "] }) : null, _jsx(Box, { flexGrow: 1, children: vimMode ? (_jsx(VimInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false, showMode: true, onModeChange: onVimModeChange })) : (_jsx(TextInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false })) })] }), _jsx(Box, { marginLeft: 1, children: _jsxs(Text, { dimColor: true, children: [busy ? _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }) : null, busy ? ' ' : '', shortModelName(model), "  \u00B7  ", balance, sessionCost > 0.00001 ? _jsxs(Text, { color: "yellow", children: ["  -$", sessionCost.toFixed(4)] }) : '', contextPct !== undefined && contextPct > 0 ? (() => {
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { borderStyle: "round", borderDimColor: true, paddingX: 1, width: boxWidth, children: [busy && !input ? _jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " "] }) : null, _jsx(Box, { flexGrow: 1, children: vimMode ? (_jsx(VimInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false, showMode: true, onModeChange: onVimModeChange })) : (_jsx(TextInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false })) })] }), _jsx(Box, { marginLeft: 1, children: _jsxs(Text, { dimColor: true, children: [busy ? _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }) : null, busy ? ' ' : '', shortModelName(model), "  \u00B7  ", balance, sessionCost > 0.00001 ? _jsxs(Text, { color: "yellow", children: ["  -$", sessionCost.toFixed(4)] }) : '', contextPct !== undefined && contextPct > 0 ? (() => {
                             // Visual context bar: ▓▓▓▓▓▓░░░░ 75%
                             const filled = Math.round(contextPct / 10);
                             const empty = 10 - filled;
@@ -52,6 +56,28 @@ function InputBox({ input, setInput, onSubmit, model, balance, sessionCost, queu
                             return (_jsxs(Text, { children: ['  ', _jsx(Text, { color: barColor, children: '▓'.repeat(filled) }), _jsx(Text, { dimColor: true, children: '░'.repeat(empty) }), _jsxs(Text, { color: barColor, children: [' ', contextPct, "%"] })] }));
                         })() : null, (queuedCount ?? 0) > 0 ? _jsxs(Text, { color: "cyan", children: ["  \u00B7  ", queuedCount, " queued"] }) : null, '  ·  esc'] }) })] }));
 }
+function formatAgentErrorForDisplay(error) {
+    const lines = error.split('\n').map((line) => line.trim()).filter(Boolean);
+    const tipIndex = lines.findIndex((line) => /^tip:/i.test(line));
+    const mainLines = tipIndex >= 0 ? lines.slice(0, tipIndex) : lines;
+    const tipLines = tipIndex >= 0 ? lines.slice(tipIndex) : [];
+    let main = mainLines.join(' ').replace(/\s+/g, ' ').trim();
+    let tip = tipLines.join(' ').replace(/\s+/g, ' ').trim();
+    const labelMatch = /^\[([^\]]+)\]\s*/.exec(main);
+    const label = labelMatch?.[1];
+    if (labelMatch)
+        main = main.slice(labelMatch[0].length).trim();
+    if (tip)
+        tip = tip.replace(/^tip:\s*/i, '');
+    const out = ['**Request failed**'];
+    if (label)
+        out.push(`- Type: ${label}`);
+    if (main)
+        out.push(`- Message: ${main}`);
+    if (tip)
+        out.push(`- Tip: ${tip}`);
+    return out.join('\n');
+}
 function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain, startWithPicker, onSubmit, onModelChange, onAbort, onExit, }) {
     const { exit } = useApp();
     const [input, setInput] = useState('');
@@ -635,7 +661,7 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                             setStreamText('');
                         }
                         if (event.reason === 'error' && event.error) {
-                            commitResponse(`Error: ${event.error}`, turnTokensRef.current, turnCostRef.current);
+                            commitResponse(formatAgentErrorForDisplay(event.error), turnTokensRef.current, turnCostRef.current);
                             showStatus('Turn failed', 'error', 5000);
                         }
                         else if (event.reason === 'aborted') {

package/dist/version-check.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Update-check utility.
+ *
+ * Quietly pings npm once per day, caches the latest published version in
+ * `~/.blockrun/version-check.json`, and exposes a sync helper the CLI
+ * uses to nudge users when they're behind. The check is non-blocking:
+ * fire-and-forget at startup, render the notice on the *next* run if the
+ * network was slow the first time. Users never wait on it.
+ *
+ * Respects two opt-outs:
+ *   - `FRANKLIN_NO_UPDATE_CHECK=1` — explicit user preference
+ *   - CI-like environments (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, etc.)
+ *
+ * Cache format is intentionally small and forward-compatible: new fields
+ * may be added, old fields are tolerated on read.
+ */
+/**
+ * Compare two semver strings (stripping a leading `v` and any pre-release
+ * tag after a hyphen — we don't publish prereleases). Returns:
+ *   1  if a > b
+ *  -1  if a < b
+ *   0  if equal or unparseable
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Refresh the cache in the background if it's stale. Never throws, never
+ * awaited by callers — result lands before next startup.
+ */
+export declare function kickoffVersionCheck(): void;
+export interface UpdateInfo {
+    current: string;
+    latest: string;
+}
+/**
+ * Sync check against the cached latest. Returns update info if the cache
+ * knows of a newer version, null otherwise. Safe to call before the first
+ * background check settles — returns null (we don't speculate).
+ */
+export declare function getAvailableUpdate(): UpdateInfo | null;

package/dist/version-check.js

@@ -0,0 +1,134 @@
+/**
+ * Update-check utility.
+ *
+ * Quietly pings npm once per day, caches the latest published version in
+ * `~/.blockrun/version-check.json`, and exposes a sync helper the CLI
+ * uses to nudge users when they're behind. The check is non-blocking:
+ * fire-and-forget at startup, render the notice on the *next* run if the
+ * network was slow the first time. Users never wait on it.
+ *
+ * Respects two opt-outs:
+ *   - `FRANKLIN_NO_UPDATE_CHECK=1` — explicit user preference
+ *   - CI-like environments (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, etc.)
+ *
+ * Cache format is intentionally small and forward-compatible: new fields
+ * may be added, old fields are tolerated on read.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR, VERSION, USER_AGENT } from './config.js';
+const CACHE_FILE = path.join(BLOCKRUN_DIR, 'version-check.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // once per day
+const FETCH_TIMEOUT_MS = 2_000;
+const REGISTRY_URL = 'https://registry.npmjs.org/@blockrun/franklin/latest';
+function isDisabled() {
+    if (process.env.FRANKLIN_NO_UPDATE_CHECK === '1')
+        return true;
+    // Common CI signals — no point nagging headless runners.
+    return Boolean(process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.BUILDKITE ||
+        process.env.CIRCLECI);
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(CACHE_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latestVersion === 'string' && typeof parsed.checkedAt === 'number') {
+            return { latestVersion: parsed.latestVersion, checkedAt: parsed.checkedAt };
+        }
+    }
+    catch { /* no cache, bad JSON, first run — all handled by returning null */ }
+    return null;
+}
+function writeCache(data) {
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+    }
+    catch { /* cache write is best-effort — never crash startup over it */ }
+}
+/**
+ * Compare two semver strings (stripping a leading `v` and any pre-release
+ * tag after a hyphen — we don't publish prereleases). Returns:
+ *   1  if a > b
+ *  -1  if a < b
+ *   0  if equal or unparseable
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const core = v.replace(/^v/, '').split('-')[0];
+        const parts = core.split('.').map(n => Number.parseInt(n, 10));
+        if (parts.length !== 3 || parts.some(Number.isNaN))
+            return null;
+        return [parts[0], parts[1], parts[2]];
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return 1;
+        if (pa[i] < pb[i])
+            return -1;
+    }
+    return 0;
+}
+async function fetchLatestVersion() {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            signal: ctrl.signal,
+            headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Refresh the cache in the background if it's stale. Never throws, never
+ * awaited by callers — result lands before next startup.
+ */
+export function kickoffVersionCheck() {
+    if (isDisabled())
+        return;
+    const cache = readCache();
+    if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS)
+        return;
+    // Detach from the event loop so startup doesn't wait on network.
+    // Node keeps the process alive until the fetch settles, which is fine
+    // for short-lived CLI invocations and irrelevant for long-running
+    // interactive sessions.
+    void fetchLatestVersion().then(latest => {
+        if (!latest)
+            return;
+        writeCache({ latestVersion: latest, checkedAt: Date.now() });
+    });
+}
+/**
+ * Sync check against the cached latest. Returns update info if the cache
+ * knows of a newer version, null otherwise. Safe to call before the first
+ * background check settles — returns null (we don't speculate).
+ */
+export function getAvailableUpdate() {
+    if (isDisabled())
+        return null;
+    const cache = readCache();
+    if (!cache)
+        return null;
+    if (compareSemver(cache.latestVersion, VERSION) > 0) {
+        return { current: VERSION, latest: cache.latestVersion };
+    }
+    return null;
+}

package/package.json

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