@blockrun/clawrouter 0.10.0 → 0.10.2

package/README.md

@@ -33,17 +33,18 @@ One wallet, 38+ models, zero API keys.
 
 ## 📑 Quick Navigation
 
-| Section                                   | Description                 |
-| ----------------------------------------- | --------------------------- |
-| [Quick Start](#-quick-start)              | Install in 2 minutes        |
-| [Routing Profiles](#-routing-profiles)    | eco / auto / premium / free |
-| [How It Works](#-how-it-works)            | 15-dimension local routing  |
-| [Models & Pricing](#-models--pricing)     | 30+ models, full price list |
-| [Screenshots](#-screenshots)              | See it in action            |
-| [Payment](#-payment)                      | x402 non-custodial USDC     |
-| [Configuration](#%EF%B8%8F-configuration) | Environment variables       |
-| [vs OpenRouter](#-vs-openrouter)          | Why ClawRouter wins         |
-| [Support](#-support)                      | Telegram, X, founders       |
+| Section                                   | Description                    |
+| ----------------------------------------- | ------------------------------ |
+| [Quick Start](#-quick-start)              | Install in 2 minutes           |
+| [Routing Profiles](#-routing-profiles)    | eco / auto / premium / free    |
+| [How It Works](#-how-it-works)            | 15-dimension local routing     |
+| [Models & Pricing](#-models--pricing)     | 30+ models, full price list    |
+| [Screenshots](#-screenshots)              | See it in action               |
+| [Payment](#-payment)                      | x402 non-custodial USDC        |
+| [Configuration](#%EF%B8%8F-configuration) | Environment variables          |
+| [Troubleshooting](#-troubleshooting)      | `doctor` AI-powered diagnostics |
+| [vs OpenRouter](#-vs-openrouter)          | Why ClawRouter wins            |
+| [Support](#-support)                      | Telegram, X, founders          |
 
 ---
 
@@ -85,12 +86,12 @@ Choose your routing strategy with `/model <profile>`:
 Request → Weighted Scorer (15 dimensions) → Tier → Cheapest Model → Response
 ```
 
-| Tier      | ECO Model                          | AUTO Model                   | PREMIUM Model                |
-| --------- | ---------------------------------- | ---------------------------- | ---------------------------- |
-| SIMPLE    | nvidia/gpt-oss-120b (FREE)         | kimi-k2.5 ($0.60/$3.00)      | kimi-k2.5                    |
+| Tier      | ECO Model                           | AUTO Model                   | PREMIUM Model                |
+| --------- | ----------------------------------- | ---------------------------- | ---------------------------- |
+| SIMPLE    | nvidia/gpt-oss-120b (FREE)          | kimi-k2.5 ($0.60/$3.00)      | kimi-k2.5                    |
 | MEDIUM    | gemini-2.5-flash-lite ($0.10/$0.40) | grok-code-fast ($0.20/$1.50) | gpt-5.2-codex ($1.75/$14.00) |
 | COMPLEX   | gemini-2.5-flash-lite ($0.10/$0.40) | gemini-3.1-pro ($2/$12)      | claude-opus-4.6 ($5/$25)     |
-| REASONING | grok-4-fast ($0.20/$0.50)          | grok-4-fast ($0.20/$0.50)    | claude-sonnet-4.6 ($3/$15)   |
+| REASONING | grok-4-fast ($0.20/$0.50)           | grok-4-fast ($0.20/$0.50)    | claude-sonnet-4.6 ($3/$15)   |
 
 **Blended average: $2.05/M** vs $25/M for Claude Opus = **92% savings**
 
@@ -219,6 +220,48 @@ For basic usage, no configuration needed. For advanced options:
 
 ---
 
+## 🩺 Troubleshooting
+
+**When things go wrong, run the doctor:**
+
+```bash
+npx @blockrun/clawrouter doctor
+```
+
+This collects diagnostics and sends them to Claude Opus 4.6 for AI-powered analysis:
+
+```
+🩺 BlockRun Doctor v0.10.1
+
+System
+  ✓ OS: darwin arm64
+  ✓ Node: v20.11.0
+  ✓ Memory: 8.2GB free / 16.0GB
+
+Wallet
+  ✓ Address: 0x1234...abcd
+  ✓ Balance: $12.50
+
+Network
+  ✓ BlockRun API: reachable (142ms)
+  ✗ Local proxy: not running on :8402
+
+📤 Sending to Claude Opus 4.6...
+
+🤖 AI Analysis:
+The local proxy isn't running. Run `openclaw gateway restart` to fix.
+```
+
+**Ask a specific question:**
+
+```bash
+npx @blockrun/clawrouter doctor "why is my request failing?"
+```
+
+**Cost:** ~$0.01 per analysis (paid via your wallet balance)
+
+---
+
 ## 🛠 Development
 
 ```bash

package/dist/cli.js

@@ -1277,7 +1277,11 @@ var DEFAULT_ROUTING_CONFIG = {
     SIMPLE: {
       primary: "moonshot/kimi-k2.5",
       // $0.60/$3.00 - good for simple coding
-      fallback: ["anthropic/claude-haiku-4.5", "google/gemini-2.5-flash-lite", "xai/grok-code-fast-1"]
+      fallback: [
+        "anthropic/claude-haiku-4.5",
+        "google/gemini-2.5-flash-lite",
+        "xai/grok-code-fast-1"
+      ]
     },
     MEDIUM: {
       primary: "openai/gpt-5.2-codex",
@@ -1320,7 +1324,11 @@ var DEFAULT_ROUTING_CONFIG = {
     SIMPLE: {
       primary: "moonshot/kimi-k2.5",
       // Cheaper than Haiku ($0.5/$2.4 vs $1/$5), larger context
-      fallback: ["anthropic/claude-haiku-4.5", "xai/grok-4-1-fast-non-reasoning", "openai/gpt-4o-mini"]
+      fallback: [
+        "anthropic/claude-haiku-4.5",
+        "xai/grok-4-1-fast-non-reasoning",
+        "openai/gpt-4o-mini"
+      ]
     },
     MEDIUM: {
       primary: "xai/grok-code-fast-1",
@@ -1342,7 +1350,11 @@ var DEFAULT_ROUTING_CONFIG = {
     REASONING: {
       primary: "anthropic/claude-sonnet-4.6",
       // Strong tool use + reasoning for agentic tasks
-      fallback: ["anthropic/claude-opus-4.6", "xai/grok-4-1-fast-reasoning", "deepseek/deepseek-reasoner"]
+      fallback: [
+        "anthropic/claude-opus-4.6",
+        "xai/grok-4-1-fast-reasoning",
+        "deepseek/deepseek-reasoner"
+      ]
     }
   },
   overrides: {
@@ -4667,6 +4679,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       console.error(`[ClawRouter] Routing error: ${errorMsg}`);
+      console.error(`[ClawRouter] Run 'npx @blockrun/clawrouter doctor' for help`);
       options.onError?.(new Error(`Routing failed: ${errorMsg}`));
     }
   }
@@ -5231,6 +5244,282 @@ async function resolveOrGenerateWalletKey() {
   return { key, address, source: "generated" };
 }
 
+// src/doctor.ts
+import { platform, arch, freemem, totalmem } from "os";
+function formatBytes(bytes) {
+  const gb = bytes / (1024 * 1024 * 1024);
+  return `${gb.toFixed(1)}GB`;
+}
+function green(text) {
+  return `\x1B[32m\u2713\x1B[0m ${text}`;
+}
+function red(text) {
+  return `\x1B[31m\u2717\x1B[0m ${text}`;
+}
+function yellow(text) {
+  return `\x1B[33m\u26A0\x1B[0m ${text}`;
+}
+function collectSystemInfo() {
+  return {
+    os: `${platform()} ${arch()}`,
+    arch: arch(),
+    nodeVersion: process.version,
+    memoryFree: formatBytes(freemem()),
+    memoryTotal: formatBytes(totalmem())
+  };
+}
+async function collectWalletInfo() {
+  try {
+    const { key, address, source } = await resolveOrGenerateWalletKey();
+    if (!key || !address) {
+      return {
+        exists: false,
+        valid: false,
+        address: null,
+        balance: null,
+        isLow: false,
+        isEmpty: true,
+        source: null
+      };
+    }
+    const monitor = new BalanceMonitor(address);
+    try {
+      const balanceInfo = await monitor.checkBalance();
+      return {
+        exists: true,
+        valid: true,
+        address,
+        balance: balanceInfo.balanceUSD,
+        isLow: balanceInfo.isLow,
+        isEmpty: balanceInfo.isEmpty,
+        source
+      };
+    } catch {
+      return {
+        exists: true,
+        valid: true,
+        address,
+        balance: null,
+        isLow: false,
+        isEmpty: false,
+        source
+      };
+    }
+  } catch {
+    return {
+      exists: false,
+      valid: false,
+      address: null,
+      balance: null,
+      isLow: false,
+      isEmpty: true,
+      source: null
+    };
+  }
+}
+async function collectNetworkInfo() {
+  const port = getProxyPort();
+  let blockrunReachable = false;
+  let blockrunLatency = null;
+  try {
+    const start = Date.now();
+    const response = await fetch("https://blockrun.ai/api/v1/models", {
+      method: "GET",
+      signal: AbortSignal.timeout(1e4)
+    });
+    blockrunLatency = Date.now() - start;
+    blockrunReachable = response.ok || response.status === 402;
+  } catch {
+    blockrunReachable = false;
+  }
+  let proxyRunning = false;
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+      method: "GET",
+      signal: AbortSignal.timeout(3e3)
+    });
+    proxyRunning = response.ok;
+  } catch {
+    proxyRunning = false;
+  }
+  return {
+    blockrunApi: { reachable: blockrunReachable, latencyMs: blockrunLatency },
+    localProxy: { running: proxyRunning, port }
+  };
+}
+async function collectLogInfo() {
+  try {
+    const stats = await getStats(1);
+    return {
+      requestsLast24h: stats.totalRequests,
+      costLast24h: `$${stats.totalCost.toFixed(4)}`,
+      errorsFound: 0
+      // TODO: parse error logs
+    };
+  } catch {
+    return {
+      requestsLast24h: 0,
+      costLast24h: "$0.00",
+      errorsFound: 0
+    };
+  }
+}
+function identifyIssues(result) {
+  const issues = [];
+  if (!result.wallet.exists) {
+    issues.push("No wallet found");
+  }
+  if (result.wallet.isEmpty) {
+    issues.push("Wallet is empty - need to fund with USDC on Base");
+  } else if (result.wallet.isLow) {
+    issues.push("Wallet balance is low (< $1.00)");
+  }
+  if (!result.network.blockrunApi.reachable) {
+    issues.push("Cannot reach BlockRun API - check internet connection");
+  }
+  if (!result.network.localProxy.running) {
+    issues.push(`Local proxy not running on port ${result.network.localProxy.port}`);
+  }
+  return issues;
+}
+function printDiagnostics(result) {
+  console.log("\n\u{1F50D} Collecting diagnostics...\n");
+  console.log("System");
+  console.log(`  ${green(`OS: ${result.system.os}`)}`);
+  console.log(`  ${green(`Node: ${result.system.nodeVersion}`)}`);
+  console.log(`  ${green(`Memory: ${result.system.memoryFree} free / ${result.system.memoryTotal}`)}`);
+  console.log("\nWallet");
+  if (result.wallet.exists && result.wallet.valid) {
+    console.log(`  ${green(`Key: ${WALLET_FILE} (${result.wallet.source})`)}`);
+    console.log(`  ${green(`Address: ${result.wallet.address}`)}`);
+    if (result.wallet.isEmpty) {
+      console.log(`  ${red(`Balance: $0.00 - NEED TO FUND!`)}`);
+    } else if (result.wallet.isLow) {
+      console.log(`  ${yellow(`Balance: ${result.wallet.balance} (low)`)}`);
+    } else if (result.wallet.balance) {
+      console.log(`  ${green(`Balance: ${result.wallet.balance}`)}`);
+    } else {
+      console.log(`  ${yellow(`Balance: checking...`)}`);
+    }
+  } else {
+    console.log(`  ${red("No wallet found")}`);
+  }
+  console.log("\nNetwork");
+  if (result.network.blockrunApi.reachable) {
+    console.log(`  ${green(`BlockRun API: reachable (${result.network.blockrunApi.latencyMs}ms)`)}`);
+  } else {
+    console.log(`  ${red("BlockRun API: unreachable")}`);
+  }
+  if (result.network.localProxy.running) {
+    console.log(`  ${green(`Local proxy: running on :${result.network.localProxy.port}`)}`);
+  } else {
+    console.log(`  ${red(`Local proxy: not running on :${result.network.localProxy.port}`)}`);
+  }
+  console.log("\nLogs");
+  console.log(`  ${green(`Last 24h: ${result.logs.requestsLast24h} requests, ${result.logs.costLast24h} spent`)}`);
+  if (result.logs.errorsFound > 0) {
+    console.log(`  ${yellow(`${result.logs.errorsFound} errors found in logs`)}`);
+  }
+  if (result.issues.length > 0) {
+    console.log("\n\u26A0\uFE0F  Issues Found:");
+    for (const issue of result.issues) {
+      console.log(`  \u2022 ${issue}`);
+    }
+  }
+}
+async function analyzeWithAI(diagnostics, userQuestion) {
+  if (diagnostics.wallet.isEmpty) {
+    console.log("\n\u{1F4B3} Wallet is empty - cannot call AI for analysis.");
+    console.log(`   Fund your wallet with USDC on Base: ${diagnostics.wallet.address}`);
+    console.log("   Get USDC: https://www.coinbase.com/price/usd-coin");
+    console.log("   Bridge to Base: https://bridge.base.org\n");
+    return;
+  }
+  console.log("\n\u{1F4E4} Sending to Claude Opus 4.6...\n");
+  try {
+    const { key } = await resolveOrGenerateWalletKey();
+    const { fetch: paymentFetch } = createPaymentFetch(key);
+    const response = await paymentFetch(
+      "https://blockrun.ai/api/v1/chat/completions",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          model: "anthropic/claude-opus-4.6",
+          stream: false,
+          messages: [
+            {
+              role: "system",
+              content: `You are a technical support expert for BlockRun and ClawRouter.
+Analyze the diagnostics and:
+1. Identify the root cause of any issues
+2. Provide specific, actionable fix commands (bash)
+3. Explain why the issue occurred briefly
+4. Be concise but thorough
+5. Format commands in code blocks`
+            },
+            {
+              role: "user",
+              content: userQuestion ? `Here are my system diagnostics:
+
+${JSON.stringify(diagnostics, null, 2)}
+
+User's question: ${userQuestion}` : `Here are my system diagnostics:
+
+${JSON.stringify(diagnostics, null, 2)}
+
+Please analyze and help me fix any issues.`
+            }
+          ],
+          max_tokens: 1e3
+        })
+      },
+      void 0
+    );
+    if (!response.ok) {
+      const text = await response.text();
+      console.log(`Error: ${response.status} - ${text}`);
+      return;
+    }
+    const data = await response.json();
+    const content = data.choices?.[0]?.message?.content;
+    if (content) {
+      console.log("\u{1F916} AI Analysis:\n");
+      console.log(content);
+      console.log();
+    } else {
+      console.log("Error: No response from AI");
+    }
+  } catch (err) {
+    console.log(`
+Error calling AI: ${err instanceof Error ? err.message : String(err)}`);
+    console.log("Try again or check your wallet balance.\n");
+  }
+}
+async function runDoctor(userQuestion) {
+  console.log(`
+\u{1FA7A} BlockRun Doctor v${VERSION}
+`);
+  const [system, wallet, network, logs] = await Promise.all([
+    collectSystemInfo(),
+    collectWalletInfo(),
+    collectNetworkInfo(),
+    collectLogInfo()
+  ]);
+  const result = {
+    version: VERSION,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    system,
+    wallet,
+    network,
+    logs,
+    issues: []
+  };
+  result.issues = identifyIssues(result);
+  printDiagnostics(result);
+  await analyzeWithAI(result, userQuestion);
+}
+
 // src/cli.ts
 function printHelp() {
   console.log(`
@@ -5238,12 +5527,17 @@ ClawRouter v${VERSION} - Smart LLM Router
 
 Usage:
   clawrouter [options]
+  clawrouter doctor         Run AI-powered diagnostics
 
 Options:
   --version, -v     Show version number
   --help, -h        Show this help message
   --port <number>   Port to listen on (default: ${getProxyPort()})
 
+Commands:
+  doctor [question] Diagnose issues and get AI-powered fix suggestions
+                    Optional: Add your question for targeted help
+
 Examples:
   # Start standalone proxy (survives gateway restarts)
   npx @blockrun/clawrouter
@@ -5251,6 +5545,12 @@ Examples:
   # Start on custom port
   npx @blockrun/clawrouter --port 9000
 
+  # Run diagnostics when something isn't working
+  npx @blockrun/clawrouter doctor
+
+  # Ask a specific question
+  npx @blockrun/clawrouter doctor "why is my request failing?"
+
   # Production deployment with PM2
   pm2 start "npx @blockrun/clawrouter" --name clawrouter
 
@@ -5262,13 +5562,15 @@ For more info: https://github.com/BlockRunAI/ClawRouter
 `);
 }
 function parseArgs(args) {
-  const result = { version: false, help: false, port: void 0 };
+  const result = { version: false, help: false, doctor: false, port: void 0 };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--version" || arg === "-v") {
       result.version = true;
     } else if (arg === "--help" || arg === "-h") {
       result.help = true;
+    } else if (arg === "doctor" || arg === "--doctor") {
+      result.doctor = true;
     } else if (arg === "--port" && args[i + 1]) {
       result.port = parseInt(args[i + 1], 10);
       i++;
@@ -5286,6 +5588,13 @@ async function main() {
     printHelp();
     process.exit(0);
   }
+  if (args.doctor) {
+    const rawArgs = process.argv.slice(2);
+    const doctorIndex = rawArgs.findIndex((a) => a === "doctor" || a === "--doctor");
+    const userQuestion = rawArgs.slice(doctorIndex + 1).join(" ").trim() || void 0;
+    await runDoctor(userQuestion);
+    process.exit(0);
+  }
   const { key: walletKey, address, source } = await resolveOrGenerateWalletKey();
   if (source === "generated") {
     console.log(`[ClawRouter] Generated new wallet: ${address}`);
@@ -5316,6 +5625,7 @@ async function main() {
       console.error(
         `[ClawRouter] Insufficient funds. Balance: ${info.balanceUSD}, Need: ${info.requiredUSD}`
       );
+      console.error(`[ClawRouter] Run 'npx @blockrun/clawrouter doctor' for funding help`);
     }
   });
   const monitor = new BalanceMonitor(address);
@@ -5352,6 +5662,7 @@ async function main() {
 }
 main().catch((err) => {
   console.error(`[ClawRouter] Fatal error: ${err.message}`);
+  console.error(`[ClawRouter] Run 'npx @blockrun/clawrouter doctor' for AI-powered diagnostics`);
   process.exit(1);
 });
 //# sourceMappingURL=cli.js.map