@blockrun/cc 0.8.2 → 0.9.1

package/LICENSE

@@ -4,7 +4,7 @@ Licensor: BlockRun AI (Piebald LLC)
 
 Licensed Work: brcc
 
-Change Date: 2030-03-23
+Change Date: 2036-03-24
 
 Change License: MIT
 

package/README.md

@@ -18,7 +18,7 @@ You're paying $200/month and still can't work.<br><br>
 [![npm downloads](https://img.shields.io/npm/dm/@blockrun/cc.svg?style=flat-square&color=blue)](https://npmjs.com/package/@blockrun/cc)
 [![GitHub stars](https://img.shields.io/github/stars/BlockRunAI/brcc?style=flat-square)](https://github.com/BlockRunAI/brcc)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
-[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-orange?style=flat-square)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-BUSL--1.1-orange?style=flat-square)](LICENSE)
 
 [![x402 Protocol](https://img.shields.io/badge/x402-Micropayments-purple?style=flat-square)](https://x402.org)
 [![Base Network](https://img.shields.io/badge/Base-USDC-0052FF?style=flat-square&logo=coinbase&logoColor=white)](https://base.org)
@@ -110,13 +110,43 @@ That's it. Claude Code opens with access to 40+ models, no rate limits.
 ### From the command line
 
 ```bash
-brcc start                                # Default (Claude Sonnet 4.6)
-brcc start --model nvidia/gpt-oss-120b    # Free — no USDC needed
-brcc start --model openai/gpt-5.4         # GPT-5.4
-brcc start --model deepseek/deepseek-chat # Budget coding ($0.28/M)
+brcc start                                # Default: smart routing (blockrun/auto)
+brcc start --model blockrun/eco           # Cheapest capable model
+brcc start --model blockrun/premium       # Best quality
+brcc start --model blockrun/free          # Free tier only
+brcc start --model deepseek/deepseek-chat # Direct model access
 brcc start --model anthropic/claude-opus-4.6  # Most capable
 ```
 
+### Smart Routing (Built-in)
+
+brcc includes ClawRouter's 15-dimension classifier for automatic model selection:
+
+| Profile | Strategy | Savings | Best For |
+|---------|----------|---------|----------|
+| `blockrun/auto` | Balanced (default) | 74-100% | General use |
+| `blockrun/eco` | Cheapest possible | 95-100% | Maximum savings |
+| `blockrun/premium` | Best quality | 0% | Mission-critical |
+| `blockrun/free` | Free tier only | 100% | Zero cost |
+
+**How it works:**
+```
+"What is 2+2?"              → SIMPLE   → gemini-flash    ($0.0002)
+"Write a React component"   → MEDIUM   → kimi-k2.5       ($0.002)
+"Design a microservice..."  → COMPLEX  → gemini-3.1-pro  ($0.007)
+"Prove this theorem..."     → REASONING → grok-4-fast    ($0.0004)
+```
+
+**In-session switching:**
+```
+use auto      # Switch to smart routing
+use eco       # Switch to cheapest
+use premium   # Switch to best quality
+use free      # Switch to free models
+use sonnet    # Direct Claude Sonnet
+use deepseek  # Direct DeepSeek
+```
+
 ### Inside Claude Code
 
 Use `/model` to switch between Sonnet, Opus, and Haiku. Each maps to the BlockRun model you've configured:
@@ -172,6 +202,7 @@ Paid Models
 | `brcc start [--model <id>]` | Start proxy + launch Claude Code |
 | `brcc models` | List all models with pricing |
 | `brcc balance` | Check wallet USDC balance |
+| `brcc stats` | View usage statistics and savings |
 | `brcc config set <key> <value>` | Configure model mappings |
 | `brcc config list` | View current settings |
 
@@ -190,11 +221,55 @@ Your wallet is saved to `~/.blockrun/` and shared with all BlockRun tools.
 ```bash
 brcc start                              # Default model
 brcc start --model nvidia/gpt-oss-120b  # Free model
-brcc start --model openai/gpt-5.4      # Specific model
+brcc start --model openai/gpt-5.4       # Specific model
 brcc start --no-launch                  # Proxy only mode
+brcc start --no-fallback                # Disable auto-fallback
 brcc start -p 9000                      # Custom port
 ```
 
+### `brcc stats`
+
+View your usage statistics and cost savings:
+
+```bash
+$ brcc stats
+
+📊 brcc Usage Statistics
+
+───────────────────────────────────────────────────────────
+
+  Overview (7 days)
+
+    Requests:       1,234
+    Total Cost:     $4.5672
+    Avg per Request: $0.003701
+    Input Tokens:   2,456,000
+    Output Tokens:  892,000
+    Fallbacks:      23 (1.9%)
+
+  By Model
+
+    anthropic/claude-sonnet-4.6
+      450 req · $2.1340 (46.7%) · 245ms avg
+    deepseek/deepseek-chat
+      620 req · $0.8901 (19.5%) · 180ms avg
+      ↳ 12 fallback recoveries
+    nvidia/gpt-oss-120b
+      164 req · $0.0000 (0%) · 320ms avg
+
+  💰 Savings vs Claude Opus
+
+    Opus equivalent: $34.62
+    Your actual cost: $4.57
+    Saved: $30.05 (86.8%)
+
+───────────────────────────────────────────────────────────
+  Run `brcc stats --clear` to reset statistics
+
+$ brcc stats --clear   # Reset all statistics
+$ brcc stats --json    # Output as JSON (for scripts)
+```
+
 ### `brcc config`
 
 ```bash
@@ -207,6 +282,36 @@ brcc config list
 
 ---
 
+## Automatic Fallback
+
+When a model returns an error (429 rate limit, 500+ server error), brcc automatically retries with backup models. This ensures your work never stops.
+
+**Default fallback chain:**
+```
+anthropic/claude-sonnet-4.6
+    ↓ (if 429/500/502/503/504)
+google/gemini-2.5-pro
+    ↓
+deepseek/deepseek-chat
+    ↓
+xai/grok-4-fast
+    ↓
+nvidia/gpt-oss-120b (free, always available)
+```
+
+**How it looks:**
+```
+[brcc] ⚠️  anthropic/claude-sonnet-4.6 returned 429, falling back to google/gemini-2.5-pro
+[brcc] ↺ Fallback successful: using google/gemini-2.5-pro
+```
+
+To disable fallback:
+```bash
+brcc start --no-fallback
+```
+
+---
+
 ## How It Works
 
 ```
@@ -277,4 +382,4 @@ Yes. GPT-5, Gemini, DeepSeek, Grok, and 30+ others work through Claude Code via
 
 ## License
 
-[Business Source License 1.1](LICENSE) — Free to use, modify, and deploy. Cannot be used to build a competing hosted service. Converts to MIT in 2030.
+[Business Source License 1.1](LICENSE) — Free to use, modify, and deploy. Cannot be used to build a competing hosted service. Converts to MIT in 2036.

package/dist/commands/start.d.ts

@@ -2,6 +2,7 @@ interface StartOptions {
     port?: string;
     model?: string;
     launch?: boolean;
+    fallback?: boolean;
     debug?: boolean;
 }
 export declare function startCommand(options: StartOptions): Promise<void>;

package/dist/commands/start.js

@@ -7,6 +7,7 @@ import { loadConfig } from './config.js';
 export async function startCommand(options) {
     const chain = loadChain();
     const apiUrl = API_URLS[chain];
+    const fallbackEnabled = options.fallback !== false; // Default true
     if (chain === 'solana') {
         const wallet = await getOrCreateSolanaWallet();
         if (wallet.isNew) {
@@ -19,13 +20,21 @@ export async function startCommand(options) {
         const shouldLaunch = options.launch !== false;
         const model = options.model;
         console.log(chalk.bold('brcc — BlockRun Claude Code\n'));
-        console.log(`Chain:   ${chalk.magenta('solana')}`);
-        console.log(`Wallet:  ${chalk.cyan(wallet.address)}`);
+        console.log(`Chain:    ${chalk.magenta('solana')}`);
+        console.log(`Wallet:   ${chalk.cyan(wallet.address)}`);
         if (model)
-            console.log(`Model:   ${chalk.green(model)}`);
-        console.log(`Proxy:   ${chalk.cyan(`http://localhost:${port}`)}`);
-        console.log(`Backend: ${chalk.dim(apiUrl)}\n`);
-        const server = createProxy({ port, apiUrl, chain: 'solana', modelOverride: model, debug: options.debug });
+            console.log(`Model:    ${chalk.green(model)}`);
+        console.log(`Fallback: ${fallbackEnabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+        console.log(`Proxy:    ${chalk.cyan(`http://localhost:${port}`)}`);
+        console.log(`Backend:  ${chalk.dim(apiUrl)}\n`);
+        const server = createProxy({
+            port,
+            apiUrl,
+            chain: 'solana',
+            modelOverride: model,
+            debug: options.debug,
+            fallbackEnabled,
+        });
         launchServer(server, port, shouldLaunch, model);
     }
     else {
@@ -40,19 +49,29 @@ export async function startCommand(options) {
         const shouldLaunch = options.launch !== false;
         const model = options.model;
         console.log(chalk.bold('brcc — BlockRun Claude Code\n'));
-        console.log(`Chain:   ${chalk.magenta('base')}`);
-        console.log(`Wallet:  ${chalk.cyan(wallet.address)}`);
+        console.log(`Chain:    ${chalk.magenta('base')}`);
+        console.log(`Wallet:   ${chalk.cyan(wallet.address)}`);
         if (model)
-            console.log(`Model:   ${chalk.green(model)}`);
-        console.log(`Proxy:   ${chalk.cyan(`http://localhost:${port}`)}`);
-        console.log(`Backend: ${chalk.dim(apiUrl)}\n`);
-        const server = createProxy({ port, apiUrl, chain: 'base', modelOverride: model, debug: options.debug });
+            console.log(`Model:    ${chalk.green(model)}`);
+        console.log(`Fallback: ${fallbackEnabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+        console.log(`Proxy:    ${chalk.cyan(`http://localhost:${port}`)}`);
+        console.log(`Backend:  ${chalk.dim(apiUrl)}\n`);
+        const server = createProxy({
+            port,
+            apiUrl,
+            chain: 'base',
+            modelOverride: model,
+            debug: options.debug,
+            fallbackEnabled,
+        });
         launchServer(server, port, shouldLaunch, model);
     }
 }
 function launchServer(server, port, shouldLaunch, model) {
     server.listen(port, () => {
-        console.log(chalk.green(`Proxy running on port ${port}\n`));
+        console.log(chalk.green(`✓ Proxy running on port ${port}`));
+        console.log(chalk.dim(`  Usage tracking: ~/.blockrun/brcc-stats.json`));
+        console.log(chalk.dim(`  Run 'brcc stats' to view statistics\n`));
         if (shouldLaunch) {
             console.log('Starting Claude Code...\n');
             const cleanEnv = { ...process.env };

package/dist/commands/stats.d.ts

@@ -0,0 +1,10 @@
+/**
+ * brcc stats command
+ * Display usage statistics and cost savings
+ */
+interface StatsOptions {
+    clear?: boolean;
+    json?: boolean;
+}
+export declare function statsCommand(options: StatsOptions): void;
+export {};

package/dist/commands/stats.js

@@ -0,0 +1,94 @@
+/**
+ * brcc 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📊 brcc Usage Statistics\n'));
+    console.log('─'.repeat(55));
+    if (stats.totalRequests === 0) {
+        console.log(chalk.gray('\n  No requests recorded yet. Start using brcc!\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 `brcc stats --clear` to reset statistics\n'));
+}

package/dist/index.js

@@ -5,12 +5,13 @@ 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';
 const program = new Command();
 program
     .name('brcc')
     .description('BlockRun Claude Code — run Claude Code with any model, pay with USDC.\n\n' +
     'Use /model inside Claude Code to switch between models on the fly.')
-    .version('0.5.0');
+    .version('0.9.0');
 program
     .command('setup [chain]')
     .description('Create a new wallet for payments (base or solana)')
@@ -21,6 +22,7 @@ program
     .option('-p, --port <port>', 'Proxy port', '8402')
     .option('-m, --model <model>', 'Default model (e.g. openai/gpt-5.4, anthropic/claude-sonnet-4.6)')
     .option('--no-launch', 'Start proxy only, do not launch Claude Code')
+    .option('--no-fallback', 'Disable automatic fallback to backup models')
     .option('--debug', 'Enable debug logging')
     .action(startCommand);
 program
@@ -36,4 +38,10 @@ program
     .description('Manage brcc 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.parse();

package/dist/proxy/fallback.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback chain for brcc
+ * Automatically switches to backup models when primary fails (429, 5xx, etc.)
+ */
+export interface FallbackConfig {
+    /** Models to try in order of priority */
+    chain: string[];
+    /** HTTP status codes that trigger fallback */
+    retryOn: number[];
+    /** Maximum retries across all models */
+    maxRetries: number;
+    /** Delay between retries in ms */
+    retryDelayMs: number;
+}
+export declare const DEFAULT_FALLBACK_CONFIG: FallbackConfig;
+export interface FallbackResult {
+    response: Response;
+    modelUsed: string;
+    fallbackUsed: boolean;
+    attemptsCount: number;
+    failedModels: string[];
+}
+/**
+ * Fetch with automatic fallback to backup models
+ */
+export declare function fetchWithFallback(url: string, init: RequestInit, originalBody: string, config?: FallbackConfig, onFallback?: (model: string, statusCode: number, nextModel: string) => void): Promise<FallbackResult>;
+/**
+ * Get the current model from fallback chain based on parsed request
+ */
+export declare function getCurrentModelFromChain(requestedModel: string | undefined, config?: FallbackConfig): string;
+/**
+ * Build fallback chain starting from a specific model
+ */
+export declare function buildFallbackChain(startModel: string, config?: FallbackConfig): string[];

package/dist/proxy/fallback.js

@@ -0,0 +1,115 @@
+/**
+ * Fallback chain for brcc
+ * Automatically switches to backup models when primary fails (429, 5xx, etc.)
+ */
+export const DEFAULT_FALLBACK_CONFIG = {
+    chain: [
+        'blockrun/auto', // Smart routing (default)
+        'blockrun/eco', // Cheapest capable model
+        'deepseek/deepseek-chat', // Direct fallback
+        'nvidia/gpt-oss-120b', // Free model as ultimate fallback
+    ],
+    retryOn: [429, 500, 502, 503, 504, 529],
+    maxRetries: 5,
+    retryDelayMs: 1000,
+};
+/**
+ * Sleep helper
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Replace model in request body
+ */
+function replaceModelInBody(body, newModel) {
+    try {
+        const parsed = JSON.parse(body);
+        parsed.model = newModel;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        return body;
+    }
+}
+/**
+ * Fetch with automatic fallback to backup models
+ */
+export async function fetchWithFallback(url, init, originalBody, config = DEFAULT_FALLBACK_CONFIG, onFallback) {
+    const failedModels = [];
+    let attempts = 0;
+    for (let i = 0; i < config.chain.length && attempts < config.maxRetries; i++) {
+        const model = config.chain[i];
+        const body = replaceModelInBody(originalBody, model);
+        try {
+            attempts++;
+            const response = await fetch(url, {
+                ...init,
+                body,
+            });
+            // Success or non-retryable error
+            if (!config.retryOn.includes(response.status)) {
+                return {
+                    response,
+                    modelUsed: model,
+                    fallbackUsed: i > 0,
+                    attemptsCount: attempts,
+                    failedModels,
+                };
+            }
+            // Retryable error - log and try next
+            failedModels.push(model);
+            const nextModel = config.chain[i + 1];
+            if (nextModel && onFallback) {
+                onFallback(model, response.status, nextModel);
+            }
+            // Wait before trying next model (with exponential backoff for same model retries)
+            if (i < config.chain.length - 1) {
+                await sleep(config.retryDelayMs);
+            }
+        }
+        catch (err) {
+            // Network error - try next model
+            failedModels.push(model);
+            const nextModel = config.chain[i + 1];
+            if (nextModel && onFallback) {
+                const errMsg = err instanceof Error ? err.message : 'Network error';
+                onFallback(model, 0, nextModel);
+                console.error(`[fallback] ${model} network error: ${errMsg}`);
+            }
+            if (i < config.chain.length - 1) {
+                await sleep(config.retryDelayMs);
+            }
+        }
+    }
+    // All models failed - throw error
+    throw new Error(`All models in fallback chain failed: ${failedModels.join(', ')}`);
+}
+/**
+ * Get the current model from fallback chain based on parsed request
+ */
+export function getCurrentModelFromChain(requestedModel, config = DEFAULT_FALLBACK_CONFIG) {
+    // If model is explicitly set and in chain, start from there
+    if (requestedModel) {
+        const index = config.chain.indexOf(requestedModel);
+        if (index >= 0) {
+            return requestedModel;
+        }
+        // Model not in chain, use as-is (user specified custom model)
+        return requestedModel;
+    }
+    // Default to first model in chain
+    return config.chain[0];
+}
+/**
+ * Build fallback chain starting from a specific model
+ */
+export function buildFallbackChain(startModel, config = DEFAULT_FALLBACK_CONFIG) {
+    const index = config.chain.indexOf(startModel);
+    if (index >= 0) {
+        // Start from this model and include all after it
+        return config.chain.slice(index);
+    }
+    // Model not in default chain - prepend it
+    return [startModel, ...config.chain];
+}

package/dist/proxy/server.d.ts

@@ -6,6 +6,7 @@ export interface ProxyOptions {
     chain?: Chain;
     modelOverride?: string;
     debug?: boolean;
+    fallbackEnabled?: boolean;
 }
 export declare function createProxy(options: ProxyOptions): http.Server;
 type RequestCategory = 'simple' | 'code' | 'default';