@blockrun/franklin 3.0.0

package/dist/commands/stats.js

@@ -0,0 +1,94 @@
+/**
+ * runcode stats command
+ * Display usage statistics and cost savings
+ */
+import chalk from 'chalk';
+import { clearStats, getStatsSummary } from '../stats/tracker.js';
+export function statsCommand(options) {
+    if (options.clear) {
+        clearStats();
+        console.log(chalk.green('✓ Statistics cleared'));
+        return;
+    }
+    const { stats, opusCost, saved, savedPct, avgCostPerRequest, period } = getStatsSummary();
+    // JSON output for programmatic access
+    if (options.json) {
+        console.log(JSON.stringify({
+            ...stats,
+            computed: {
+                opusCost,
+                saved,
+                savedPct,
+                avgCostPerRequest,
+                period,
+            },
+        }, null, 2));
+        return;
+    }
+    // Pretty output
+    console.log(chalk.bold('\n📊 runcode Usage Statistics\n'));
+    console.log('─'.repeat(55));
+    if (stats.totalRequests === 0) {
+        console.log(chalk.gray('\n  No requests recorded yet. Start using runcode!\n'));
+        console.log('─'.repeat(55) + '\n');
+        return;
+    }
+    // Overview
+    console.log(chalk.bold('\n  Overview') + chalk.gray(` (${period})\n`));
+    console.log(`    Requests:       ${chalk.cyan(stats.totalRequests.toLocaleString())}`);
+    console.log(`    Total Cost:     ${chalk.green('$' + stats.totalCostUsd.toFixed(4))}`);
+    console.log(`    Avg per Request: ${chalk.gray('$' + avgCostPerRequest.toFixed(6))}`);
+    console.log(`    Input Tokens:   ${stats.totalInputTokens.toLocaleString()}`);
+    console.log(`    Output Tokens:  ${stats.totalOutputTokens.toLocaleString()}`);
+    if (stats.totalFallbacks > 0) {
+        const fallbackPct = ((stats.totalFallbacks / stats.totalRequests) *
+            100).toFixed(1);
+        console.log(`    Fallbacks:      ${chalk.yellow(stats.totalFallbacks.toString())} (${fallbackPct}%)`);
+    }
+    // Per-model breakdown
+    const modelEntries = Object.entries(stats.byModel);
+    if (modelEntries.length > 0) {
+        console.log(chalk.bold('\n  By Model\n'));
+        // Sort by cost (descending)
+        const sorted = modelEntries.sort((a, b) => b[1].costUsd - a[1].costUsd);
+        for (const [model, data] of sorted) {
+            const pct = stats.totalCostUsd > 0
+                ? ((data.costUsd / stats.totalCostUsd) * 100).toFixed(1)
+                : '0';
+            const avgLatency = Math.round(data.avgLatencyMs);
+            // Shorten model name if too long
+            const displayModel = model.length > 35 ? model.slice(0, 32) + '...' : model;
+            console.log(`    ${chalk.cyan(displayModel)}`);
+            console.log(chalk.gray(`      ${data.requests} req · $${data.costUsd.toFixed(4)} (${pct}%) · ${avgLatency}ms avg`));
+            if (data.fallbackCount > 0) {
+                console.log(chalk.yellow(`      ↳ ${data.fallbackCount} fallback recoveries`));
+            }
+        }
+    }
+    // Savings comparison
+    console.log(chalk.bold('\n  💰 Savings vs Claude Opus\n'));
+    if (opusCost > 0) {
+        console.log(`    Opus equivalent: ${chalk.gray('$' + opusCost.toFixed(2))}`);
+        console.log(`    Your actual cost:${chalk.green(' $' + stats.totalCostUsd.toFixed(2))}`);
+        console.log(`    ${chalk.green.bold(`Saved: $${saved.toFixed(2)} (${savedPct.toFixed(1)}%)`)}`);
+    }
+    else {
+        console.log(chalk.gray('    Not enough data to calculate savings'));
+    }
+    // Recent activity (last 5 requests)
+    if (stats.history.length > 0) {
+        console.log(chalk.bold('\n  Recent Activity\n'));
+        const recent = stats.history.slice(-5).reverse();
+        for (const record of recent) {
+            const time = new Date(record.timestamp).toLocaleTimeString();
+            const model = record.model.split('/').pop() || record.model;
+            const cost = '$' + record.costUsd.toFixed(4);
+            const fallbackMark = record.fallback ? chalk.yellow(' ↺') : '';
+            console.log(chalk.gray(`    ${time}`) +
+                ` ${model}${fallbackMark} ` +
+                chalk.green(cost));
+        }
+    }
+    console.log('\n' + '─'.repeat(55));
+    console.log(chalk.gray('  Run `runcode stats --clear` to reset statistics\n'));
+}

package/dist/commands/uninit.d.ts

@@ -0,0 +1 @@
+export declare function uninitCommand(): Promise<void>;

package/dist/commands/uninit.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import chalk from 'chalk';
+const CLAUDE_SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.json');
+const LAUNCH_AGENT_PLIST = path.join(os.homedir(), 'Library', 'LaunchAgents', 'ai.blockrun.runcode.plist');
+export async function uninitCommand() {
+    let changed = false;
+    // ── 1. Remove env section from ~/.claude/settings.json ──────────────────
+    try {
+        if (fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+            const settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8'));
+            const env = settings.env;
+            if (env) {
+                const proxyKeys = [
+                    'ANTHROPIC_BASE_URL',
+                    'ANTHROPIC_AUTH_TOKEN',
+                    'ANTHROPIC_MODEL',
+                    'ANTHROPIC_DEFAULT_SONNET_MODEL',
+                    'ANTHROPIC_DEFAULT_OPUS_MODEL',
+                    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+                ];
+                let removed = false;
+                for (const k of proxyKeys) {
+                    if (k in env) {
+                        delete env[k];
+                        removed = true;
+                    }
+                }
+                if (Object.keys(env).length === 0)
+                    delete settings.env;
+                if (removed) {
+                    fs.writeFileSync(CLAUDE_SETTINGS_FILE, JSON.stringify(settings, null, 2));
+                    console.log(chalk.green(`✓ Removed runcode env from ${CLAUDE_SETTINGS_FILE}`));
+                    changed = true;
+                }
+            }
+        }
+    }
+    catch (e) {
+        console.log(chalk.yellow(`Could not update settings.json: ${e.message}`));
+    }
+    // ── 2. Unload and remove LaunchAgent ────────────────────────────────────
+    if (process.platform === 'darwin' && fs.existsSync(LAUNCH_AGENT_PLIST)) {
+        try {
+            const { execSync } = await import('node:child_process');
+            execSync(`launchctl unload -w "${LAUNCH_AGENT_PLIST}"`, { stdio: 'pipe' });
+        }
+        catch { /* already unloaded */ }
+        fs.unlinkSync(LAUNCH_AGENT_PLIST);
+        console.log(chalk.green(`✓ Removed LaunchAgent`));
+        changed = true;
+    }
+    if (!changed) {
+        console.log(chalk.dim('Nothing to uninit — runcode was not initialized.'));
+    }
+    else {
+        console.log('');
+        console.log(chalk.bold('runcode uninitialized.'));
+        console.log(`Claude Code will use its default Anthropic API settings again.`);
+        console.log(`Run ${chalk.bold('runcode daemon stop')} to stop any running proxy.`);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export declare const VERSION: string;
+export declare const USER_AGENT: string;
+export type Chain = 'base' | 'solana';
+export declare const BLOCKRUN_DIR: string;
+export declare const CHAIN_FILE: string;
+export declare const API_URLS: Record<Chain, string>;
+export declare const DEFAULT_PROXY_PORT = 8402;
+export declare function saveChain(chain: Chain): void;
+export declare function loadChain(): Chain;

package/dist/config.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+let _version = '2.0.0';
+try {
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf-8'));
+    _version = pkg.version || _version;
+}
+catch { /* use default */ }
+export const VERSION = _version;
+// Shared User-Agent string for all outbound HTTP requests
+export const USER_AGENT = `runcode/${_version} (node/${process.versions.node}; ${process.platform}; ${process.arch})`;
+export const BLOCKRUN_DIR = path.join(os.homedir(), '.blockrun');
+export const CHAIN_FILE = path.join(BLOCKRUN_DIR, 'payment-chain');
+export const API_URLS = {
+    base: 'https://blockrun.ai/api',
+    solana: 'https://sol.blockrun.ai/api',
+};
+export const DEFAULT_PROXY_PORT = 8402;
+export function saveChain(chain) {
+    fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+    fs.writeFileSync(CHAIN_FILE, chain + '\n', { mode: 0o600 });
+}
+export function loadChain() {
+    const envChain = process.env.RUNCODE_CHAIN;
+    if (envChain === 'solana')
+        return 'solana';
+    if (envChain === 'base')
+        return 'base';
+    try {
+        const content = fs.readFileSync(CHAIN_FILE, 'utf-8').trim();
+        if (content === 'solana')
+            return 'solana';
+        return 'base';
+    }
+    catch {
+        return 'base';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Global error handlers — catch unhandled rejections/exceptions before they crash silently
+process.on('unhandledRejection', (reason) => {
+    console.error(`\x1b[31mUnhandled error: ${reason instanceof Error ? reason.message : String(reason)}\x1b[0m`);
+    process.exit(1);
+});
+process.on('uncaughtException', (err) => {
+    console.error(`\x1b[31mFatal error: ${err.message}\x1b[0m`);
+    process.exit(1);
+});
+import { Command } from 'commander';
+import { flushStats } from './stats/tracker.js';
+// Ensure stats are flushed on any exit
+process.on('exit', () => flushStats());
+import { setupCommand } from './commands/setup.js';
+import { startCommand } from './commands/start.js';
+import { balanceCommand } from './commands/balance.js';
+import { modelsCommand } from './commands/models.js';
+import { configCommand } from './commands/config.js';
+import { statsCommand } from './commands/stats.js';
+import { logsCommand } from './commands/logs.js';
+import { daemonCommand } from './commands/daemon.js';
+import { initCommand } from './commands/init.js';
+import { uninitCommand } from './commands/uninit.js';
+import { proxyCommand } from './commands/proxy.js';
+import { VERSION as version } from './config.js';
+const program = new Command();
+program
+    .name('franklin')
+    .description('Franklin — The AI agent with a wallet.\n\n' +
+    'While others chat, Franklin spends — turning your USDC into real work.\n\n' +
+    '  Marketing workflows:  franklin.run\n' +
+    '  Trading workflows:    franklin.bet\n\n' +
+    'Pay per action in USDC on Base or Solana. No subscriptions. No accounts.')
+    .version(version);
+program
+    .command('setup [chain]')
+    .description('Create a new wallet for payments (base or solana)')
+    .action((chain) => setupCommand(chain));
+program
+    .command('start')
+    .description('Start the runcode agent')
+    .option('-m, --model <model>', 'Model to use (e.g. openai/gpt-5.4, anthropic/claude-sonnet-4.6). Default from config or claude-sonnet-4.6')
+    .option('--debug', 'Enable debug logging')
+    .option('--trust', 'Trust mode — skip permission prompts for all tools')
+    .action((options) => startCommand({ ...options, version }));
+program
+    .command('proxy')
+    .description('Run payment proxy for Claude Code or other tools')
+    .option('-p, --port <port>', 'Proxy port', '8402')
+    .option('-m, --model <model>', 'Default model for proxied requests')
+    .option('--no-fallback', 'Disable automatic fallback to backup models')
+    .option('--debug', 'Enable debug logging')
+    .action((options) => proxyCommand({ ...options, version }));
+program
+    .command('init')
+    .description('Configure runcode auto-start (writes ~/.claude/settings.json + installs LaunchAgent on macOS)')
+    .option('-p, --port <port>', 'Proxy port', '8402')
+    .action((options) => initCommand(options));
+program
+    .command('uninit')
+    .description('Remove runcode configuration and uninstall LaunchAgent')
+    .action(() => uninitCommand());
+program
+    .command('daemon <action>')
+    .description('Manage runcode background proxy (start|stop|status)')
+    .option('-p, --port <port>', 'Proxy port', '8402')
+    .action((action, options) => daemonCommand(action, options));
+program
+    .command('models')
+    .description('List available models and pricing')
+    .action(modelsCommand);
+program
+    .command('balance')
+    .description('Check wallet USDC balance')
+    .action(balanceCommand);
+program
+    .command('config <action> [key] [value]')
+    .description('Manage runcode config (set, get, unset, list)\n' +
+    'Keys: default-model, sonnet-model, opus-model, haiku-model, smart-routing')
+    .action(configCommand);
+program
+    .command('stats')
+    .description('Show usage statistics and cost savings')
+    .option('--clear', 'Clear all statistics')
+    .option('--json', 'Output in JSON format')
+    .action(statsCommand);
+program
+    .command('logs')
+    .description('View debug logs (start with --debug to enable logging)')
+    .option('-f, --follow', 'Follow log output in real time')
+    .option('-n, --lines <count>', 'Number of lines to show (default: 50)')
+    .option('--clear', 'Delete log file')
+    .action(logsCommand);
+program
+    .command('insights')
+    .description('Show rich usage insights — cost breakdown, trends, projections')
+    .option('-d, --days <n>', 'Window size in days (default: 30)', '30')
+    .action(async (opts) => {
+    const { generateInsights, formatInsights } = await import('./stats/insights.js');
+    const days = parseInt(opts.days ?? '30', 10) || 30;
+    const report = generateInsights(days);
+    process.stdout.write(formatInsights(report, days));
+});
+program
+    .command('search <query>')
+    .description('Search past sessions by keyword (use quotes for phrases)')
+    .option('-l, --limit <n>', 'Max results to show (default: 10)', '10')
+    .option('-m, --model <substring>', 'Filter by model name substring')
+    .action(async (query, opts) => {
+    const { searchSessions, formatSearchResults } = await import('./session/search.js');
+    const limit = parseInt(opts.limit ?? '10', 10) || 10;
+    const matches = searchSessions(query, { limit, model: opts.model });
+    process.stdout.write(formatSearchResults(matches, query));
+});
+// Plugin commands — dynamically registered from discovered plugins.
+// Core stays plugin-agnostic: this loop adds a command for each installed plugin.
+{
+    const { loadAllPlugins, listWorkflowPlugins } = await import('./plugins/registry.js');
+    await loadAllPlugins();
+    for (const lp of listWorkflowPlugins()) {
+        const { manifest } = lp;
+        program
+            .command(`${manifest.id} [action]`)
+            .description(manifest.description)
+            .option('--dry', 'Dry run — preview without side effects')
+            .option('--debug', 'Enable debug logging')
+            .action(async (action, opts) => {
+            const { pluginCommand } = await import('./commands/plugin.js');
+            await pluginCommand(manifest.id, action, { dryRun: opts.dry, debug: opts.debug });
+        });
+    }
+}
+program
+    .command('plugins')
+    .description('List installed plugins')
+    .action(async () => {
+    const { listAvailablePlugins } = await import('./commands/plugin.js');
+    listAvailablePlugins();
+});
+// Default action: if no subcommand given, run 'start'
+const args = process.argv.slice(2);
+const knownCommands = program.commands.map(c => c.name());
+const firstArg = args[0];
+// Handle chain shortcuts: `runcode solana` or `runcode base`
+if (firstArg === 'solana' || firstArg === 'base') {
+    const { saveChain } = await import('./config.js');
+    saveChain(firstArg);
+    const startOpts = { version };
+    for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--trust')
+            startOpts.trust = true;
+        else if (args[i] === '--debug')
+            startOpts.debug = true;
+        else if ((args[i] === '-m' || args[i] === '--model') && args[i + 1]) {
+            startOpts.model = args[++i];
+        }
+    }
+    await startCommand(startOpts);
+    process.exit(0);
+}
+else if (!firstArg || (firstArg.startsWith('-') && !['-h', '--help', '-V', '--version'].includes(firstArg))) {
+    // No subcommand or only flags — treat as 'start' with flags
+    const startOpts = { version };
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--trust')
+            startOpts.trust = true;
+        else if (args[i] === '--debug')
+            startOpts.debug = true;
+        else if ((args[i] === '-m' || args[i] === '--model') && args[i + 1]) {
+            startOpts.model = args[++i];
+        }
+    }
+    await startCommand(startOpts);
+    process.exit(0);
+}
+else {
+    program.parse();
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP Client for runcode.
+ * Connects to MCP servers, discovers tools, and wraps them as CapabilityHandlers.
+ * Supports stdio and HTTP (SSE) transports.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export interface McpServerConfig {
+    /** Transport type */
+    transport: 'stdio' | 'http';
+    /** For stdio: command to run */
+    command?: string;
+    /** For stdio: arguments */
+    args?: string[];
+    /** For stdio: environment variables */
+    env?: Record<string, string>;
+    /** For http: server URL */
+    url?: string;
+    /** For http: headers */
+    headers?: Record<string, string>;
+    /** Human-readable label */
+    label?: string;
+    /** Disable this server */
+    disabled?: boolean;
+}
+export interface McpConfig {
+    mcpServers: Record<string, McpServerConfig>;
+}
+/**
+ * Connect to all configured MCP servers and return discovered tools.
+ * Each connection has a 5s timeout to avoid blocking startup.
+ */
+export declare function connectMcpServers(config: McpConfig, debug?: boolean): Promise<CapabilityHandler[]>;
+/**
+ * Disconnect all MCP servers.
+ */
+export declare function disconnectMcpServers(): Promise<void>;
+/**
+ * List connected MCP servers and their tools.
+ */
+export declare function listMcpServers(): Array<{
+    name: string;
+    toolCount: number;
+    tools: string[];
+}>;

package/dist/mcp/client.js

@@ -0,0 +1,147 @@
+/**
+ * MCP Client for runcode.
+ * Connects to MCP servers, discovers tools, and wraps them as CapabilityHandlers.
+ * Supports stdio and HTTP (SSE) transports.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+// ─── Connection Management ────────────────────────────────────────────────
+const connections = new Map();
+/**
+ * Connect to an MCP server via stdio transport.
+ * Discovers tools and returns them as CapabilityHandlers.
+ */
+async function connectStdio(name, config) {
+    if (!config.command) {
+        throw new Error(`MCP server "${name}" missing command`);
+    }
+    const transport = new StdioClientTransport({
+        command: config.command,
+        args: config.args || [],
+        env: { ...process.env, ...(config.env || {}) },
+    });
+    const client = new Client({ name: `runcode-mcp-${name}`, version: '1.0.0' }, { capabilities: {} });
+    try {
+        await client.connect(transport);
+    }
+    catch (err) {
+        // Clean up transport if connect fails to prevent resource leak
+        try {
+            await transport.close();
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+    // Discover tools
+    const { tools: mcpTools } = await client.listTools();
+    const capabilities = [];
+    for (const tool of mcpTools) {
+        const toolName = `mcp__${name}__${tool.name}`;
+        const toolDescription = (tool.description || '').slice(0, 2048);
+        capabilities.push({
+            spec: {
+                name: toolName,
+                description: toolDescription || `MCP tool from ${name}`,
+                input_schema: tool.inputSchema || {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            execute: async (input, _ctx) => {
+                const MCP_TOOL_TIMEOUT = 30_000;
+                try {
+                    // Timeout protection: if tool hangs, don't block the agent forever
+                    const callPromise = client.callTool({ name: tool.name, arguments: input });
+                    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`MCP tool timeout after ${MCP_TOOL_TIMEOUT / 1000}s`)), MCP_TOOL_TIMEOUT));
+                    const result = await Promise.race([callPromise, timeoutPromise]);
+                    // Extract text content from MCP response
+                    const output = result.content
+                        ?.filter(c => c.type === 'text')
+                        ?.map(c => c.text)
+                        ?.join('\n') || JSON.stringify(result.content);
+                    return {
+                        output,
+                        isError: result.isError === true,
+                    };
+                }
+                catch (err) {
+                    return {
+                        output: `MCP tool error (${name}/${tool.name}): ${err.message}`,
+                        isError: true,
+                    };
+                }
+            },
+            concurrent: true, // MCP tools are safe to run concurrently
+        });
+    }
+    const connected = { name, client, transport, tools: capabilities };
+    connections.set(name, connected);
+    return connected;
+}
+/**
+ * Connect to all configured MCP servers and return discovered tools.
+ */
+const MCP_CONNECT_TIMEOUT = 5_000; // 5s per server connection
+/**
+ * Connect to all configured MCP servers and return discovered tools.
+ * Each connection has a 5s timeout to avoid blocking startup.
+ */
+export async function connectMcpServers(config, debug) {
+    const allTools = [];
+    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+        if (serverConfig.disabled)
+            continue;
+        try {
+            if (debug) {
+                console.error(`[runcode] Connecting to MCP server: ${name}...`);
+            }
+            if (serverConfig.transport !== 'stdio') {
+                if (debug) {
+                    console.error(`[runcode] MCP HTTP transport not yet supported for ${name}`);
+                }
+                continue;
+            }
+            // Timeout: don't let a slow server block startup
+            const connectPromise = connectStdio(name, serverConfig);
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('connection timeout (5s)')), MCP_CONNECT_TIMEOUT));
+            const connected = await Promise.race([connectPromise, timeoutPromise]);
+            allTools.push(...connected.tools);
+            if (debug) {
+                console.error(`[runcode] MCP ${name}: ${connected.tools.length} tools discovered`);
+            }
+        }
+        catch (err) {
+            // Graceful degradation — log and continue without this server
+            console.error(`[runcode] MCP ${name} failed: ${err.message}`);
+        }
+    }
+    return allTools;
+}
+/**
+ * Disconnect all MCP servers.
+ */
+export async function disconnectMcpServers() {
+    for (const [name, conn] of connections) {
+        try {
+            await conn.client.close();
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        connections.delete(name);
+    }
+}
+/**
+ * List connected MCP servers and their tools.
+ */
+export function listMcpServers() {
+    const result = [];
+    for (const [name, conn] of connections) {
+        result.push({
+            name,
+            toolCount: conn.tools.length,
+            tools: conn.tools.map(t => t.spec.name),
+        });
+    }
+    return result;
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP configuration management for runcode.
+ * Loads MCP server configs from:
+ * 1. Global: ~/.blockrun/mcp.json
+ * 2. Project: .mcp.json in working directory
+ */
+import type { McpConfig, McpServerConfig } from './client.js';
+export declare function loadMcpConfig(workDir: string): McpConfig;
+/**
+ * Save a server config to the global MCP config.
+ */
+export declare function saveMcpServer(name: string, config: McpServerConfig): void;
+/**
+ * Remove a server from the global MCP config.
+ */
+export declare function removeMcpServer(name: string): boolean;
+/**
+ * Trust a project directory to load its .mcp.json.
+ */
+export declare function trustProjectDir(workDir: string): void;