@blockrun/franklin 3.0.0

package/dist/agent/streaming-executor.js

@@ -0,0 +1,149 @@
+/**
+ * Streaming Tool Executor for runcode.
+ * Starts executing concurrent-safe tools while the model is still streaming.
+ * Non-concurrent tools wait until the full response is received.
+ */
+export class StreamingExecutor {
+    handlers;
+    scope;
+    permissions;
+    onStart;
+    onProgress;
+    pending = [];
+    constructor(opts) {
+        this.handlers = opts.handlers;
+        this.scope = opts.scope;
+        this.permissions = opts.permissions;
+        this.onStart = opts.onStart;
+        this.onProgress = opts.onProgress;
+    }
+    /**
+     * Called when a tool_use block is fully received from the stream.
+     * If the tool is concurrent-safe, start executing immediately.
+     * Otherwise, queue it for later.
+     */
+    onToolReceived(invocation) {
+        const handler = this.handlers.get(invocation.name);
+        const isConcurrent = handler?.concurrent ?? false;
+        if (isConcurrent) {
+            // Concurrent tools are auto-allowed — start immediately and time from here
+            const preview = this.inputPreview(invocation);
+            this.onStart(invocation.id, invocation.name, preview);
+            const promise = this.executeWithPermissions(invocation, 1, false);
+            this.pending.push({ invocation, promise });
+        }
+        // Non-concurrent tools are NOT started here — executed via collectResults
+    }
+    /**
+     * After the model finishes streaming, execute any non-concurrent tools
+     * and collect all results (including concurrent ones that may already be done).
+     */
+    async collectResults(allInvocations) {
+        const results = [];
+        const alreadyStarted = new Set(this.pending.map(p => p.invocation.id));
+        const pendingSnapshot = [...this.pending];
+        this.pending = []; // Clear immediately so errors don't leave stale state
+        // Pre-count pending sequential invocations per tool type.
+        // Shown in permission dialog: "N pending — press [a] to allow all".
+        const pendingCounts = new Map();
+        for (const inv of allInvocations) {
+            if (!alreadyStarted.has(inv.id)) {
+                pendingCounts.set(inv.name, (pendingCounts.get(inv.name) || 0) + 1);
+            }
+        }
+        const remainingCounts = new Map(pendingCounts);
+        try {
+            // Wait for concurrent results that were started during streaming
+            for (const p of pendingSnapshot) {
+                const result = await p.promise;
+                results.push([p.invocation, result]);
+            }
+            // Execute sequential (non-concurrent) tools now
+            for (const inv of allInvocations) {
+                if (alreadyStarted.has(inv.id))
+                    continue;
+                const remaining = remainingCounts.get(inv.name) ?? 1;
+                remainingCounts.set(inv.name, remaining - 1);
+                // NOTE: onStart is called INSIDE executeWithPermissions, AFTER permission is granted.
+                // This ensures elapsed time reflects actual execution time, not permission wait time.
+                const result = await this.executeWithPermissions(inv, remaining, true);
+                results.push([inv, result]);
+            }
+        }
+        catch (err) {
+            // Return partial results rather than losing them; caller handles errors
+            throw err;
+        }
+        return results;
+    }
+    async executeWithPermissions(invocation, pendingCount = 1, callStart = true // false for concurrent tools (already called in onToolReceived)
+    ) {
+        // Permission check
+        if (this.permissions) {
+            const decision = await this.permissions.check(invocation.name, invocation.input);
+            if (decision.behavior === 'deny') {
+                return {
+                    output: `Permission denied for ${invocation.name}: ${decision.reason || 'denied by policy'}. Do not retry — explain to the user what you were trying to do and ask how they'd like to proceed.`,
+                    isError: true,
+                };
+            }
+            if (decision.behavior === 'ask') {
+                const allowed = await this.permissions.promptUser(invocation.name, invocation.input, pendingCount);
+                if (!allowed) {
+                    return {
+                        output: `User denied permission for ${invocation.name}. Do not retry — ask the user what they'd like to do instead.`,
+                        isError: true,
+                    };
+                }
+            }
+        }
+        // Start timing AFTER permission is granted (accurate elapsed time)
+        if (callStart) {
+            const preview = this.inputPreview(invocation);
+            this.onStart(invocation.id, invocation.name, preview);
+        }
+        const handler = this.handlers.get(invocation.name);
+        if (!handler) {
+            return { output: `Unknown capability: ${invocation.name}`, isError: true };
+        }
+        // Wire per-invocation progress to onProgress callback
+        const progressScope = this.onProgress
+            ? {
+                ...this.scope,
+                onProgress: (text) => this.onProgress(invocation.id, text),
+            }
+            : this.scope;
+        try {
+            return await handler.execute(invocation.input, progressScope);
+        }
+        catch (err) {
+            return {
+                output: `Error executing ${invocation.name}: ${err.message}`,
+                isError: true,
+            };
+        }
+    }
+    /** Extract a short preview string from a tool invocation's input. */
+    inputPreview(invocation) {
+        const input = invocation.input;
+        switch (invocation.name) {
+            case 'Bash': {
+                const cmd = input.command || '';
+                return cmd.length > 80 ? cmd.slice(0, 80) + '…' : cmd;
+            }
+            case 'Write':
+            case 'Read':
+            case 'Edit':
+                return input.file_path || undefined;
+            case 'Grep':
+                return input.pattern || undefined;
+            case 'Glob':
+                return input.pattern || undefined;
+            case 'WebFetch':
+            case 'WebSearch':
+                return (input.url ?? input.query) || undefined;
+            default:
+                return undefined;
+        }
+    }
+}

package/dist/agent/tokens.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Token estimation for runcode.
+ * Uses byte-based heuristic (no external tokenizer dependency).
+ * Anchors to actual API counts when available, estimates on top for new messages.
+ */
+import type { Dialogue } from './types.js';
+/**
+ * Update with actual token counts from API response.
+ * This anchors our estimates to reality.
+ */
+export declare function updateActualTokens(inputTokens: number, outputTokens: number, messageCount: number): void;
+/**
+ * Get token count using API anchor + estimation for new messages.
+ * More accurate than pure estimation because it's grounded in actual API counts.
+ */
+export declare function getAnchoredTokenCount(history: Dialogue[]): {
+    estimated: number;
+    apiAnchored: boolean;
+    contextUsagePct: number;
+};
+/**
+ * Reset anchor (e.g., after compaction).
+ */
+export declare function resetTokenAnchor(): void;
+/**
+ * Estimate token count for a string using byte-length heuristic.
+ * JSON-heavy content uses 2 bytes/token; general text uses 4.
+ */
+export declare function estimateTokens(text: string, bytesPerToken?: number): number;
+/**
+ * Estimate total tokens for a message.
+ */
+export declare function estimateDialogueTokens(msg: Dialogue): number;
+/**
+ * Estimate total tokens for the entire conversation history.
+ */
+export declare function estimateHistoryTokens(history: Dialogue[]): number;
+/**
+ * Get the context window size for a model, with a conservative default.
+ */
+export declare function getContextWindow(model: string): number;
+/**
+ * Reserved tokens for the compaction summary output.
+ */
+export declare const COMPACTION_SUMMARY_RESERVE = 16000;
+/**
+ * Buffer before hitting the context limit to trigger auto-compact.
+ */
+export declare const COMPACTION_TRIGGER_BUFFER = 12000;
+/**
+ * Calculate the threshold at which auto-compaction should trigger.
+ */
+export declare function getCompactionThreshold(model: string): number;

package/dist/agent/tokens.js

@@ -0,0 +1,185 @@
+/**
+ * Token estimation for runcode.
+ * Uses byte-based heuristic (no external tokenizer dependency).
+ * Anchors to actual API counts when available, estimates on top for new messages.
+ */
+const DEFAULT_BYTES_PER_TOKEN = 4;
+// ─── API-anchored token tracking ───────────────────────���──────────────────
+/** Last known actual token count from API response */
+let lastApiInputTokens = 0;
+let lastApiOutputTokens = 0;
+let lastApiMessageCount = 0;
+/**
+ * Update with actual token counts from API response.
+ * This anchors our estimates to reality.
+ */
+export function updateActualTokens(inputTokens, outputTokens, messageCount) {
+    lastApiInputTokens = inputTokens;
+    lastApiOutputTokens = outputTokens;
+    lastApiMessageCount = messageCount;
+}
+/**
+ * Get token count using API anchor + estimation for new messages.
+ * More accurate than pure estimation because it's grounded in actual API counts.
+ */
+export function getAnchoredTokenCount(history) {
+    if (lastApiInputTokens > 0 && lastApiMessageCount > 0 && history.length >= lastApiMessageCount) {
+        // Sanity check: if history was mutated (compaction, micro-compact), anchor may be stale.
+        // Detect by checking if new messages were only appended (length grew), not if content changed.
+        // If history grew by more than expected (e.g., resume injected many messages), fall through to estimation.
+        const growth = history.length - lastApiMessageCount;
+        if (growth <= 20) { // Reasonable growth since last API call
+            const newMessages = history.slice(lastApiMessageCount);
+            let newTokens = 0;
+            for (const msg of newMessages) {
+                newTokens += estimateDialogueTokens(msg);
+            }
+            const total = lastApiInputTokens + newTokens;
+            return {
+                estimated: total,
+                apiAnchored: true,
+                contextUsagePct: 0,
+            };
+        }
+        // Too much growth — anchor is unreliable, fall through to estimation
+        resetTokenAnchor();
+    }
+    // No anchor — pure estimation
+    return {
+        estimated: estimateHistoryTokens(history),
+        apiAnchored: false,
+        contextUsagePct: 0,
+    };
+}
+/**
+ * Reset anchor (e.g., after compaction).
+ */
+export function resetTokenAnchor() {
+    lastApiInputTokens = 0;
+    lastApiOutputTokens = 0;
+    lastApiMessageCount = 0;
+}
+/**
+ * Estimate token count for a string using byte-length heuristic.
+ * JSON-heavy content uses 2 bytes/token; general text uses 4.
+ */
+export function estimateTokens(text, bytesPerToken = DEFAULT_BYTES_PER_TOKEN) {
+    // Pad by 4/3 (~33%) for conservative estimation — better to over-count than under-count
+    return Math.ceil(Buffer.byteLength(text, 'utf-8') / bytesPerToken * 1.33);
+}
+/**
+ * Estimate tokens for a content part.
+ */
+function estimateContentPartTokens(part) {
+    switch (part.type) {
+        case 'text':
+            return estimateTokens(part.text);
+        case 'tool_use':
+            // +16 tokens for tool_use framing (type, id, name fields, JSON structure)
+            return 16 + estimateTokens(part.name) + estimateTokens(JSON.stringify(part.input), 2);
+        case 'tool_result': {
+            const content = typeof part.content === 'string'
+                ? part.content
+                : JSON.stringify(part.content);
+            return estimateTokens(content, 2);
+        }
+        case 'thinking':
+            return estimateTokens(part.thinking);
+        default:
+            return 0;
+    }
+}
+/**
+ * Estimate total tokens for a message.
+ */
+export function estimateDialogueTokens(msg) {
+    const overhead = 4; // role, structure overhead
+    if (typeof msg.content === 'string') {
+        return overhead + estimateTokens(msg.content);
+    }
+    let total = overhead;
+    for (const part of msg.content) {
+        total += estimateContentPartTokens(part);
+    }
+    return total;
+}
+/**
+ * Estimate total tokens for the entire conversation history.
+ */
+export function estimateHistoryTokens(history) {
+    let total = 0;
+    for (const msg of history) {
+        total += estimateDialogueTokens(msg);
+    }
+    return total;
+}
+/**
+ * Context window sizes for known models.
+ */
+const MODEL_CONTEXT_WINDOWS = {
+    // Anthropic
+    'anthropic/claude-opus-4.6': 200_000,
+    'anthropic/claude-sonnet-4.6': 200_000,
+    'anthropic/claude-sonnet-4': 200_000,
+    'anthropic/claude-haiku-4.5': 200_000,
+    'anthropic/claude-haiku-4.5-20251001': 200_000,
+    // OpenAI
+    'openai/gpt-5.4': 128_000,
+    'openai/gpt-5.4-pro': 128_000,
+    'openai/gpt-5.3': 128_000,
+    'openai/gpt-5.3-codex': 128_000,
+    'openai/gpt-5.2': 128_000,
+    'openai/gpt-5-mini': 128_000,
+    'openai/gpt-5-nano': 128_000,
+    'openai/gpt-4.1': 1_000_000,
+    'openai/o3': 200_000,
+    'openai/o4-mini': 200_000,
+    // Google
+    'google/gemini-2.5-pro': 1_000_000,
+    'google/gemini-2.5-flash': 1_000_000,
+    'google/gemini-2.5-flash-lite': 1_000_000,
+    'google/gemini-3.1-pro': 1_000_000,
+    // DeepSeek
+    'deepseek/deepseek-chat': 64_000,
+    'deepseek/deepseek-reasoner': 64_000,
+    // xAI
+    'xai/grok-3': 131_072,
+    'xai/grok-4-0709': 131_072,
+    'xai/grok-4-1-fast-reasoning': 131_072,
+    // Others
+    'zai/glm-5.1': 128_000,
+    'moonshot/kimi-k2.5': 128_000,
+    'minimax/minimax-m2.7': 128_000,
+};
+/**
+ * Get the context window size for a model, with a conservative default.
+ */
+export function getContextWindow(model) {
+    if (MODEL_CONTEXT_WINDOWS[model])
+        return MODEL_CONTEXT_WINDOWS[model];
+    // Pattern-based inference for unknown models
+    if (model.includes('gemini'))
+        return 1_000_000;
+    if (model.includes('claude'))
+        return 200_000;
+    if (model.includes('gpt-4.1'))
+        return 1_000_000;
+    if (model.includes('nemotron') || model.includes('qwen'))
+        return 128_000;
+    return 128_000;
+}
+/**
+ * Reserved tokens for the compaction summary output.
+ */
+export const COMPACTION_SUMMARY_RESERVE = 16_000;
+/**
+ * Buffer before hitting the context limit to trigger auto-compact.
+ */
+export const COMPACTION_TRIGGER_BUFFER = 12_000;
+/**
+ * Calculate the threshold at which auto-compaction should trigger.
+ */
+export function getCompactionThreshold(model) {
+    const window = getContextWindow(model);
+    return window - COMPACTION_SUMMARY_RESERVE - COMPACTION_TRIGGER_BUFFER;
+}

package/dist/agent/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Core types for the runcode agent system.
+ * All type names and structures are original designs.
+ */
+export type Role = 'user' | 'assistant';
+export interface TextSegment {
+    type: 'text';
+    text: string;
+}
+export interface CapabilityInvocation {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ThinkingSegment {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+}
+export interface CapabilityOutcome {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | ContentPart[];
+    is_error?: boolean;
+}
+export type ContentPart = TextSegment | CapabilityInvocation | ThinkingSegment;
+export type UserContentPart = TextSegment | CapabilityOutcome;
+export interface Dialogue {
+    role: Role;
+    content: ContentPart[] | UserContentPart[] | string;
+}
+export interface CapabilitySchema {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+export interface CapabilityDefinition {
+    name: string;
+    description: string;
+    input_schema: CapabilitySchema;
+}
+export interface CapabilityHandler {
+    spec: CapabilityDefinition;
+    execute(input: Record<string, unknown>, ctx: ExecutionScope): Promise<CapabilityResult>;
+    concurrent?: boolean;
+}
+export interface CapabilityResult {
+    output: string;
+    isError?: boolean;
+}
+export interface ExecutionScope {
+    workingDir: string;
+    abortSignal: AbortSignal;
+    onProgress?: (text: string) => void;
+    /** Routes AskUser questions through ink UI input to avoid raw-mode stdin conflict */
+    onAskUser?: (question: string, options?: string[]) => Promise<string>;
+}
+export interface StreamTextDelta {
+    kind: 'text_delta';
+    text: string;
+}
+export interface StreamThinkingDelta {
+    kind: 'thinking_delta';
+    text: string;
+}
+export interface StreamCapabilityStart {
+    kind: 'capability_start';
+    id: string;
+    name: string;
+    preview?: string;
+}
+export interface StreamCapabilityInputDelta {
+    kind: 'capability_input_delta';
+    id: string;
+    delta: string;
+}
+export interface StreamCapabilityProgress {
+    kind: 'capability_progress';
+    id: string;
+    text: string;
+}
+export interface StreamCapabilityDone {
+    kind: 'capability_done';
+    id: string;
+    result: CapabilityResult;
+}
+export interface StreamTurnDone {
+    kind: 'turn_done';
+    reason: 'completed' | 'max_turns' | 'aborted' | 'error';
+    error?: string;
+}
+export interface StreamUsageInfo {
+    kind: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    model: string;
+    calls: number;
+}
+export type StreamEvent = StreamTextDelta | StreamThinkingDelta | StreamCapabilityStart | StreamCapabilityInputDelta | StreamCapabilityProgress | StreamCapabilityDone | StreamTurnDone | StreamUsageInfo;
+export interface AgentConfig {
+    model: string;
+    apiUrl: string;
+    chain: 'base' | 'solana';
+    systemInstructions: string[];
+    capabilities: CapabilityHandler[];
+    maxTurns?: number;
+    workingDir?: string;
+    permissionMode?: 'default' | 'trust' | 'deny-all' | 'plan';
+    onEvent?: (event: StreamEvent) => void;
+    debug?: boolean;
+    /** Ultrathink mode: inject deep-reasoning instruction into every prompt */
+    ultrathink?: boolean;
+    /**
+     * Permission prompt function — injected by Ink UI to avoid stdin conflict.
+     * Replaces the readline-based askQuestion() when running in interactive mode.
+     * Returns 'yes' | 'no' | 'always' (always = allow for rest of session).
+     */
+    permissionPromptFn?: (toolName: string, description: string) => Promise<'yes' | 'no' | 'always'>;
+    /** Routes AskUser questions through ink UI input to avoid raw-mode stdin conflict */
+    onAskUser?: (question: string, options?: string[]) => Promise<string>;
+    /** Notify UI when agent switches model (e.g. payment fallback) */
+    onModelChange?: (model: string) => void;
+}

package/dist/agent/types.js

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

package/dist/banner.d.ts

@@ -0,0 +1 @@
+export declare function printBanner(version: string): void;

package/dist/banner.js

@@ -0,0 +1,27 @@
+import chalk from 'chalk';
+// "FRANKLIN" — the AI agent with a wallet
+const FRANKLIN_ART = [
+    ' ███████╗██████╗  █████╗ ███╗   ██╗██╗  ██╗██╗     ██╗███╗   ██╗',
+    ' ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║ ██╔╝██║     ██║████╗  ██║',
+    ' █████╗  ██████╔╝███████║██╔██╗ ██║█████╔╝ ██║     ██║██╔██╗ ██║',
+    ' ██╔══╝  ██╔══██╗██╔══██║██║╚██╗██║██╔═██╗ ██║     ██║██║╚██╗██║',
+    ' ██║     ██║  ██║██║  ██║██║ ╚████║██║  ██╗███████╗██║██║ ╚████║',
+    ' ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝',
+];
+export function printBanner(version) {
+    // Gold → green gradient: money colors for "the agent with a wallet"
+    const gold = chalk.hex('#FFD700');
+    const green = chalk.hex('#10B981');
+    for (let i = 0; i < FRANKLIN_ART.length; i++) {
+        // Alternate lines between gold and green for subtle depth
+        const color = i < 3 ? gold : green;
+        console.log(color(FRANKLIN_ART[i]));
+    }
+    console.log(chalk.bold.hex('#FFD700')('  Franklin') +
+        chalk.dim('  ·  The AI agent with a wallet  ·  v' + version));
+    console.log(chalk.dim('  Marketing: ') +
+        chalk.cyan('franklin.run') +
+        chalk.dim('   ·   Trading: ') +
+        chalk.hex('#10B981')('franklin.bet') +
+        chalk.dim('\n'));
+}

package/dist/commands/balance.d.ts

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

package/dist/commands/balance.js

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+import { setupAgentWallet, setupAgentSolanaWallet } from '@blockrun/llm';
+import { loadChain } from '../config.js';
+export async function balanceCommand() {
+    const chain = loadChain();
+    try {
+        if (chain === 'solana') {
+            const client = await setupAgentSolanaWallet({ silent: true });
+            const address = await client.getWalletAddress();
+            const balance = await client.getBalance();
+            console.log(`Chain:  ${chalk.magenta('solana')}`);
+            console.log(`Wallet: ${chalk.cyan(address)}`);
+            console.log(`USDC Balance: ${chalk.green(`$${balance.toFixed(2)}`)}`);
+            if (balance === 0) {
+                console.log(chalk.dim(`\nSend USDC on Solana to ${address} to get started.`));
+            }
+        }
+        else {
+            const client = setupAgentWallet({ silent: true });
+            const address = client.getWalletAddress();
+            const balance = await client.getBalance();
+            console.log(`Chain:  ${chalk.magenta('base')}`);
+            console.log(`Wallet: ${chalk.cyan(address)}`);
+            console.log(`USDC Balance: ${chalk.green(`$${balance.toFixed(2)}`)}`);
+            if (balance === 0) {
+                console.log(chalk.dim(`\nSend USDC on Base to ${address} to get started.`));
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : '';
+        if (msg.includes('ENOENT') || msg.includes('wallet') || msg.includes('key')) {
+            console.log(chalk.red('No wallet found. Run `runcode setup` first.'));
+        }
+        else {
+            console.log(chalk.red(`Error checking balance: ${msg || 'unknown error'}`));
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,14 @@
+export interface AppConfig {
+    'default-model'?: string;
+    'sonnet-model'?: string;
+    'opus-model'?: string;
+    'haiku-model'?: string;
+    'smart-routing'?: string;
+    'permission-mode'?: string;
+    'max-turns'?: string;
+    'auto-compact'?: string;
+    'session-save'?: string;
+    'debug'?: string;
+}
+export declare function loadConfig(): AppConfig;
+export declare function configCommand(action: string, keyOrUndefined?: string, value?: string): void;