@blockrun/franklin 3.0.0

package/dist/stats/tracker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Usage tracking for runcode
+ * Records all requests with cost, tokens, and latency for stats display
+ */
+export interface UsageRecord {
+    timestamp: number;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    latencyMs: number;
+    fallback?: boolean;
+}
+export interface ModelStats {
+    requests: number;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    fallbackCount: number;
+    avgLatencyMs: number;
+    totalLatencyMs: number;
+}
+export interface Stats {
+    version: number;
+    totalRequests: number;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalFallbacks: number;
+    byModel: Record<string, ModelStats>;
+    history: UsageRecord[];
+    firstRequest?: number;
+    lastRequest?: number;
+}
+export declare function loadStats(): Stats;
+export declare function saveStats(stats: Stats): void;
+export declare function clearStats(): void;
+/** Flush stats to disk immediately (call on process exit) */
+export declare function flushStats(): void;
+/**
+ * Record a completed request for stats tracking
+ */
+export declare function recordUsage(model: string, inputTokens: number, outputTokens: number, costUsd: number, latencyMs: number, fallback?: boolean): void;
+/**
+ * Get stats summary for display
+ */
+export declare function getStatsSummary(): {
+    stats: Stats;
+    opusCost: number;
+    saved: number;
+    savedPct: number;
+    avgCostPerRequest: number;
+    period: string;
+};

package/dist/stats/tracker.js

@@ -0,0 +1,165 @@
+/**
+ * Usage tracking for runcode
+ * Records all requests with cost, tokens, and latency for stats display
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { OPUS_PRICING } from '../pricing.js';
+const STATS_FILE = path.join(os.homedir(), '.blockrun', 'runcode-stats.json');
+const EMPTY_STATS = {
+    version: 1,
+    totalRequests: 0,
+    totalCostUsd: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalFallbacks: 0,
+    byModel: {},
+    history: [],
+};
+export function loadStats() {
+    try {
+        if (fs.existsSync(STATS_FILE)) {
+            const data = JSON.parse(fs.readFileSync(STATS_FILE, 'utf-8'));
+            // Migration: add missing fields
+            return {
+                ...EMPTY_STATS,
+                ...data,
+                version: 1,
+            };
+        }
+    }
+    catch {
+        /* ignore parse errors, return empty */
+    }
+    return { ...EMPTY_STATS };
+}
+export function saveStats(stats) {
+    try {
+        fs.mkdirSync(path.dirname(STATS_FILE), { recursive: true });
+        // Keep only last 1000 history records
+        stats.history = stats.history.slice(-1000);
+        fs.writeFileSync(STATS_FILE, JSON.stringify(stats, null, 2));
+    }
+    catch {
+        /* ignore write errors */
+    }
+}
+export function clearStats() {
+    cachedStats = null;
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    try {
+        if (fs.existsSync(STATS_FILE)) {
+            fs.unlinkSync(STATS_FILE);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+// ─── In-memory stats cache with debounced write ─────────────────────────
+// Prevents concurrent load→modify→save from losing data in proxy mode
+let cachedStats = null;
+let flushTimer = null;
+const FLUSH_DELAY_MS = 2000;
+function getCachedStats() {
+    if (!cachedStats) {
+        cachedStats = loadStats();
+    }
+    return cachedStats;
+}
+function scheduleSave() {
+    if (flushTimer)
+        return; // Already scheduled
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        if (cachedStats)
+            saveStats(cachedStats);
+    }, FLUSH_DELAY_MS);
+}
+/** Flush stats to disk immediately (call on process exit) */
+export function flushStats() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    if (cachedStats)
+        saveStats(cachedStats);
+}
+/**
+ * Record a completed request for stats tracking
+ */
+export function recordUsage(model, inputTokens, outputTokens, costUsd, latencyMs, fallback = false) {
+    const stats = getCachedStats();
+    const now = Date.now();
+    // Update totals
+    stats.totalRequests++;
+    stats.totalCostUsd += costUsd;
+    stats.totalInputTokens += inputTokens;
+    stats.totalOutputTokens += outputTokens;
+    if (fallback)
+        stats.totalFallbacks++;
+    // Update timestamps
+    if (!stats.firstRequest)
+        stats.firstRequest = now;
+    stats.lastRequest = now;
+    // Update per-model stats
+    if (!stats.byModel[model]) {
+        stats.byModel[model] = {
+            requests: 0,
+            costUsd: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            fallbackCount: 0,
+            avgLatencyMs: 0,
+            totalLatencyMs: 0,
+        };
+    }
+    const modelStats = stats.byModel[model];
+    modelStats.requests++;
+    modelStats.costUsd += costUsd;
+    modelStats.inputTokens += inputTokens;
+    modelStats.outputTokens += outputTokens;
+    modelStats.totalLatencyMs += latencyMs;
+    modelStats.avgLatencyMs = modelStats.totalLatencyMs / modelStats.requests;
+    if (fallback)
+        modelStats.fallbackCount++;
+    // Add to history
+    stats.history.push({
+        timestamp: now,
+        model,
+        inputTokens,
+        outputTokens,
+        costUsd,
+        latencyMs,
+        fallback,
+    });
+    scheduleSave();
+}
+/**
+ * Get stats summary for display
+ */
+export function getStatsSummary() {
+    const stats = loadStats();
+    // Calculate what it would cost with Claude Opus
+    const opusCost = (stats.totalInputTokens / 1_000_000) * OPUS_PRICING.input +
+        (stats.totalOutputTokens / 1_000_000) * OPUS_PRICING.output;
+    const saved = opusCost - stats.totalCostUsd;
+    const savedPct = opusCost > 0 ? (saved / opusCost) * 100 : 0;
+    const avgCostPerRequest = stats.totalRequests > 0 ? stats.totalCostUsd / stats.totalRequests : 0;
+    // Calculate period
+    let period = 'No data';
+    if (stats.firstRequest && stats.lastRequest) {
+        const days = Math.ceil((stats.lastRequest - stats.firstRequest) / (1000 * 60 * 60 * 24));
+        if (days === 0)
+            period = 'Today';
+        else if (days === 1)
+            period = '1 day';
+        else
+            period = `${days} days`;
+    }
+    return { stats, opusCost, saved, savedPct, avgCostPerRequest, period };
+}

package/dist/tools/askuser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AskUser capability — let the agent ask the user a clarifying question.
+ * The question is displayed and the response is returned as tool output.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const askUserCapability: CapabilityHandler;

package/dist/tools/askuser.js

@@ -0,0 +1,76 @@
+/**
+ * AskUser capability — let the agent ask the user a clarifying question.
+ * The question is displayed and the response is returned as tool output.
+ */
+import readline from 'node:readline';
+import chalk from 'chalk';
+async function execute(input, ctx) {
+    const { question, options } = input;
+    if (!question) {
+        return { output: 'Error: question is required', isError: true };
+    }
+    // Ink UI path: use the provided callback to avoid raw-mode stdin conflict
+    if (ctx.onAskUser) {
+        try {
+            const answer = await ctx.onAskUser(question, options);
+            return { output: answer || '(no response)' };
+        }
+        catch {
+            return { output: 'User did not respond.', isError: false };
+        }
+    }
+    // Non-ink fallback (CLI piped / scripted mode)
+    if (!process.stdin.isTTY) {
+        return {
+            output: `[Non-interactive mode] Cannot prompt user. Proceed with a reasonable assumption. Question was: ${question}`,
+            isError: false,
+        };
+    }
+    // Bare TTY fallback (no ink UI) — use readline
+    console.error('');
+    console.error(chalk.yellow('  ╭─ Question ────────────────────────────'));
+    console.error(chalk.yellow(`  │ ${question}`));
+    if (options && options.length > 0) {
+        for (let i = 0; i < options.length; i++) {
+            console.error(chalk.dim(`  │ ${i + 1}. ${options[i]}`));
+        }
+    }
+    console.error(chalk.yellow('  ╰───────────────────────────────────────'));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.question(chalk.bold('  answer> '), (answer) => {
+            answered = true;
+            rl.close();
+            resolve({ output: answer.trim() || '(no response)' });
+        });
+        rl.on('close', () => {
+            if (!answered)
+                resolve({ output: 'User closed input without responding.', isError: false });
+        });
+    });
+}
+export const askUserCapability = {
+    spec: {
+        name: 'AskUser',
+        description: 'Ask the user a clarifying question. Use when you need more information before proceeding.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'The question to ask the user' },
+                options: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of suggested answers to present',
+                },
+            },
+            required: ['question'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/bash.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Bash capability — execute shell commands with timeout and output capture.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const bashCapability: CapabilityHandler;

package/dist/tools/bash.js

@@ -0,0 +1,336 @@
+/**
+ * Bash capability — execute shell commands with timeout and output capture.
+ */
+import { spawn } from 'node:child_process';
+// ─── Smart Output Compression ─────────────────────────────────────────────
+// Learned from RTK (Rust Token Killer): strip noise before sending to LLM.
+// Applied after capture, before the 32KB cap — reduces tokens on verbose commands.
+const ANSI_RE = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+function stripAnsi(s) {
+    return s.replace(ANSI_RE, '');
+}
+function collapseBlankLines(s) {
+    // Collapse 3+ consecutive blank lines → 1 blank line
+    return s.replace(/\n{3,}/g, '\n\n');
+}
+/** Extract the base command word (first non-env token). */
+function baseCmd(command) {
+    // Strip leading env var assignments (FOO=bar cmd → cmd)
+    const stripped = command.replace(/^(?:[A-Z_][A-Z0-9_]*=\S*\s+)*/, '').trimStart();
+    return stripped.split(/\s+/)[0] ?? '';
+}
+function compressOutput(command, output) {
+    // 1. Always strip ANSI escape codes
+    let out = stripAnsi(output);
+    const cmd = baseCmd(command);
+    const fullCmd = command.trimStart();
+    // 2. Git command-aware compression
+    if (cmd === 'git') {
+        const sub = fullCmd.split(/\s+/)[1] ?? '';
+        out = compressGit(sub, out);
+    }
+    // 3. Package manager installs — keep only errors + final summary
+    else if (/^(npm|pnpm|yarn|bun)\s+(install|i|add|ci)\b/.test(fullCmd)) {
+        out = compressInstall(out);
+    }
+    // 4. Test runners — keep only failures + summary line
+    else if (/^(npm|pnpm|bun)\s+test\b|^(jest|vitest|mocha)\b/.test(fullCmd)) {
+        out = compressTests(out);
+    }
+    // 5. Build commands — keep errors/warnings, drop verbose compile lines
+    else if (/^(npm|pnpm|bun)\s+(run\s+)?(build|compile)\b|^tsc\b/.test(fullCmd)) {
+        out = compressBuild(out);
+    }
+    // 6. cargo
+    else if (cmd === 'cargo') {
+        const sub = fullCmd.split(/\s+/)[1] ?? '';
+        if (sub === 'test' || sub === 'nextest')
+            out = compressTests(out);
+        else if (sub === 'build' || sub === 'check' || sub === 'clippy')
+            out = compressBuild(out);
+        else if (sub === 'install')
+            out = compressInstall(out);
+    }
+    // 7. Always collapse excessive blank lines
+    out = collapseBlankLines(out);
+    return out;
+}
+function compressGit(sub, out) {
+    switch (sub) {
+        case 'add': {
+            // git add is usually silent. Strip any blank output.
+            const trimmed = out.trim();
+            return trimmed || 'ok';
+        }
+        case 'commit': {
+            // Keep: [branch abc1234] message + stats line. Strip verbose output.
+            const lines = out.split('\n');
+            const kept = lines.filter(l => /^\[.+\]/.test(l) || // [main abc1234] commit msg
+                /\d+ file/.test(l) || // 2 files changed, 10 insertions
+                /^\s*(create|delete) mode/.test(l) ||
+                l.trim() === '');
+            return kept.join('\n').trim() || out.trim();
+        }
+        case 'push': {
+            // Strip verbose remote "enumerating/counting/compressing" lines
+            const lines = out.split('\n').filter(l => !/^remote:\s*(Enumerating|Counting|Compressing|Writing|Total|Delta)/.test(l) &&
+                !/^Counting objects|^Compressing objects|^Writing objects/.test(l) &&
+                l.trim() !== '');
+            return lines.join('\n').trim() || 'ok';
+        }
+        case 'pull': {
+            // Strip "remote: Counting..." lines, keep summary
+            const lines = out.split('\n').filter(l => !/^remote:\s*(Enumerating|Counting|Compressing|Writing|Total|Delta)/.test(l) &&
+                !/^Counting objects|^Compressing objects/.test(l));
+            return collapseBlankLines(lines.join('\n')).trim();
+        }
+        case 'fetch': {
+            const lines = out.split('\n').filter(l => !/^remote:\s*(Enumerating|Counting|Compressing|Writing|Total|Delta)/.test(l));
+            return lines.join('\n').trim();
+        }
+        case 'log': {
+            // Already terse if user uses --oneline; just collapse blanks
+            return out.trim();
+        }
+        default:
+            return out;
+    }
+}
+function compressInstall(out) {
+    const lines = out.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const l = line.trim();
+        // Drop pure progress lines
+        if (/^(Downloading|Fetching|Resolving|Progress|Preparing|Caching)/.test(l))
+            continue;
+        if (/^[\s.]*$/.test(l))
+            continue;
+        // Keep errors, warnings, and summary lines
+        kept.push(line);
+    }
+    // If no lines kept, return original trimmed (don't lose error info)
+    const result = kept.join('\n').trim();
+    return result || out.trim();
+}
+function compressTests(out) {
+    const lines = out.split('\n');
+    // Look for failure sections and summary
+    const kept = [];
+    let inFailure = false;
+    for (const line of lines) {
+        const l = line.trim();
+        // Detect failure/error blocks
+        if (/^(FAIL|FAILED|Error:|●|✕|✗|×|error\[)/.test(l)) {
+            inFailure = true;
+        }
+        // Summary lines (always keep)
+        if (/^(Tests?|Test Suites?|Suites?|PASS|FAIL|ok\s|error|warning|\d+ (test|spec|example))/.test(l) ||
+            /\d+\s*(passed|failed|skipped|pending|todo)/.test(l)) {
+            kept.push(line);
+            inFailure = false;
+            continue;
+        }
+        if (inFailure) {
+            kept.push(line);
+            // End failure block on blank line after content
+            if (l === '' && kept[kept.length - 2]?.trim() !== '')
+                inFailure = false;
+        }
+    }
+    // If nothing matched (e.g. all passed with no verbose output), return original
+    if (kept.length === 0)
+        return out.trim();
+    return collapseBlankLines(kept.join('\n')).trim();
+}
+function compressBuild(out) {
+    const lines = out.split('\n');
+    const kept = lines.filter(l => {
+        const t = l.trim();
+        if (t === '')
+            return false;
+        // Drop pure progress/info lines from bundlers/compilers
+        if (/^(Compiling|Finished|Checking|warning: unused import)/.test(t) &&
+            !/^(Compiling.*error|Finished.*error)/.test(t)) {
+            // Keep "Finished" summary
+            if (/^Finished/.test(t))
+                return true;
+            return false;
+        }
+        return true;
+    });
+    return collapseBlankLines(kept.join('\n')).trim() || out.trim();
+}
+const MAX_OUTPUT_BYTES = 512 * 1024; // 512KB capture buffer (prevents OOM)
+const MAX_RETURN_CHARS = 32_000; // 32KB return cap (~8,000 tokens) — prevents context bloat
+const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes
+async function execute(input, ctx) {
+    const { command, timeout } = input;
+    if (!command || typeof command !== 'string') {
+        return { output: 'Error: command is required', isError: true };
+    }
+    const timeoutMs = Math.min(timeout ?? DEFAULT_TIMEOUT_MS, 600_000);
+    return new Promise((resolve) => {
+        const shell = process.env.SHELL || '/bin/bash';
+        let child;
+        try {
+            child = spawn(shell, ['-c', command], {
+                cwd: ctx.workingDir,
+                env: {
+                    ...process.env,
+                    RUNCODE: '1', // Let scripts detect they're running inside runcode
+                    RUNCODE_WORKDIR: ctx.workingDir,
+                },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (spawnErr) {
+            resolve({ output: `Error spawning shell: ${spawnErr.message}`, isError: true });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let outputBytes = 0;
+        let truncated = false;
+        let killed = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already dead */ }
+            }, 5000); // Give 5s for graceful shutdown before SIGKILL
+        }, timeoutMs);
+        // Handle abort signal
+        const onAbort = () => {
+            killed = true;
+            child.kill('SIGTERM');
+        };
+        ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+        // Emit last non-empty line to UI progress (throttled to avoid flooding)
+        let lastProgressEmit = 0;
+        const emitProgress = (text) => {
+            if (!ctx.onProgress)
+                return;
+            const now = Date.now();
+            if (now - lastProgressEmit < 500)
+                return; // max 2 updates/sec
+            lastProgressEmit = now;
+            const lastLine = text.split('\n').map(l => l.trim()).filter(Boolean).pop();
+            if (lastLine)
+                ctx.onProgress(lastLine.slice(0, 120));
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (truncated)
+                return;
+            const remaining = MAX_OUTPUT_BYTES - outputBytes;
+            if (remaining <= 0) {
+                truncated = true;
+                return;
+            }
+            const text = chunk.toString('utf-8');
+            if (chunk.length <= remaining) {
+                stdout += text;
+                outputBytes += chunk.length;
+            }
+            else {
+                stdout += text.slice(0, remaining);
+                outputBytes = MAX_OUTPUT_BYTES;
+                truncated = true;
+            }
+            emitProgress(text);
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (truncated)
+                return;
+            const remaining = MAX_OUTPUT_BYTES - outputBytes;
+            if (remaining <= 0) {
+                truncated = true;
+                return;
+            }
+            const text = chunk.toString('utf-8');
+            if (chunk.length <= remaining) {
+                stderr += text;
+                outputBytes += chunk.length;
+            }
+            else {
+                stderr += text.slice(0, remaining);
+                outputBytes = MAX_OUTPUT_BYTES;
+                truncated = true;
+            }
+            emitProgress(text);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            ctx.abortSignal.removeEventListener('abort', onAbort);
+            let result = '';
+            if (stdout)
+                result += stdout;
+            if (stderr) {
+                if (result)
+                    result += '\n';
+                result += stderr;
+            }
+            if (truncated) {
+                result += '\n\n... (output truncated — command produced >512KB)';
+            }
+            // Smart compression: strip ANSI, collapse blank lines, command-aware filters
+            result = compressOutput(command, result);
+            // Cap returned output to prevent context bloat.
+            // Keep the LAST part (most relevant for errors/test failures/build output).
+            if (result.length > MAX_RETURN_CHARS) {
+                const lines = result.split('\n');
+                let trimmed = '';
+                for (let i = lines.length - 1; i >= 0; i--) {
+                    const candidate = lines[i] + '\n' + trimmed;
+                    if (candidate.length > MAX_RETURN_CHARS)
+                        break;
+                    trimmed = candidate;
+                }
+                const omitted = result.length - trimmed.length;
+                result = `... (${omitted.toLocaleString()} chars omitted from start)\n${trimmed}`;
+            }
+            if (killed) {
+                resolve({
+                    output: result + `\n\n(command killed — timeout after ${timeoutMs / 1000}s. Set timeout param up to 600000ms for longer.)`,
+                    isError: true,
+                });
+                return;
+            }
+            if (code !== 0 && code !== null) {
+                resolve({
+                    output: result || `Command exited with code ${code}`,
+                    isError: true,
+                });
+                return;
+            }
+            resolve({ output: result || '(no output)' });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            ctx.abortSignal.removeEventListener('abort', onAbort);
+            resolve({
+                output: `Error spawning command: ${err.message}`,
+                isError: true,
+            });
+        });
+    });
+}
+export const bashCapability = {
+    spec: {
+        name: 'Bash',
+        description: 'Execute a shell command and return stdout+stderr. Runs in working directory with user env. Output capped at 512KB. Default timeout: 2min, max: 10min (set via timeout param in ms).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'The shell command to execute' },
+                timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000, max: 600000)' },
+            },
+            required: ['command'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/edit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Edit capability — targeted string replacement in files.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const editCapability: CapabilityHandler;