feat: add cost savings dashboard with /stats command and web UI

- Add /stats terminal command showing ASCII usage statistics
- Add /dashboard web endpoint with interactive Chart.js charts
- Add /stats JSON API for programmatic access
- Enhanced UsageEntry to track tier, baselineCost, savings
- Dashboard shows: total saved, routing by tier, daily breakdown, top models
- Web dashboard auto-refreshes every 30 seconds

Author: 1bcMax

src/index.ts

@@ -34,6 +34,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { VERSION } from "./version.js";
 import { privateKeyToAccount } from "viem/accounts";
+import { getStats, formatStatsAscii } from "./stats.js";
 
 /**
  * Detect if we're running in shell completion mode.
@@ -279,6 +280,43 @@ async function startProxyInBackground(api: OpenClawPluginApi): Promise<void> {
   api.logger.info(`BlockRun provider active — ${proxy.baseUrl}/v1 (smart routing enabled)`);
 }
 
+/**
+ * /stats command handler for ClawRouter.
+ * Shows usage statistics and cost savings.
+ */
+async function createStatsCommand(): Promise<OpenClawPluginCommandDefinition> {
+  return {
+    name: "stats",
+    description: "Show ClawRouter usage statistics and cost savings",
+    acceptsArgs: true,
+    requireAuth: false,
+    handler: async (ctx: PluginCommandContext) => {
+      const arg = ctx.args?.trim().toLowerCase() || "7";
+      const days = parseInt(arg, 10) || 7;
+
+      try {
+        const stats = await getStats(Math.min(days, 30)); // Cap at 30 days
+        const ascii = formatStatsAscii(stats);
+
+        return {
+          text: [
+            "```",
+            ascii,
+            "```",
+            "",
+            `View detailed dashboard: http://127.0.0.1:${getProxyPort()}/dashboard`,
+          ].join("\n"),
+        };
+      } catch (err) {
+        return {
+          text: `Failed to load stats: ${err instanceof Error ? err.message : String(err)}`,
+          isError: true,
+        };
+      }
+    },
+  };
+}
+
 /**
  * /wallet command handler for ClawRouter.
  * - /wallet or /wallet status: Show wallet address, balance, and key file location
@@ -438,6 +476,17 @@ const plugin: OpenClawPluginDefinition = {
         );
       });
 
+    // Register /stats command for usage statistics
+    createStatsCommand()
+      .then((statsCommand) => {
+        api.registerCommand(statsCommand);
+      })
+      .catch((err) => {
+        api.logger.warn(
+          `Failed to register /stats command: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+
     // Register a service with stop() for cleanup on gateway shutdown
     // This prevents EADDRINUSE when the gateway restarts
     api.registerService({
@@ -501,3 +550,5 @@ export {
 } from "./errors.js";
 export { fetchWithRetry, isRetryable, DEFAULT_RETRY_CONFIG } from "./retry.js";
 export type { RetryConfig } from "./retry.js";
+export { getStats, formatStatsAscii, generateDashboardHtml } from "./stats.js";
+export type { DailyStats, AggregatedStats } from "./stats.js";

src/logger.ts

@@ -15,7 +15,10 @@ import { homedir } from "node:os";
 export type UsageEntry = {
   timestamp: string;
   model: string;
+  tier: string;
   cost: number;
+  baselineCost: number;
+  savings: number; // 0-1 percentage
   latencyMs: number;
 };
 

src/proxy.ts

@@ -36,6 +36,7 @@ import {
 } from "./router/index.js";
 import { BLOCKRUN_MODELS } from "./models.js";
 import { logUsage, type UsageEntry } from "./logger.js";
+import { getStats, generateDashboardHtml } from "./stats.js";
 import { RequestDeduplicator } from "./dedup.js";
 import { BalanceMonitor } from "./balance.js";
 import { InsufficientFundsError, EmptyWalletError } from "./errors.js";
@@ -411,6 +412,53 @@ export async function startProxy(options: ProxyOptions): Promise<ProxyHandle> {
       return;
     }
 
+    // Dashboard endpoint - serves HTML analytics page
+    if (req.url === "/dashboard" || req.url?.startsWith("/dashboard?")) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const days = parseInt(url.searchParams.get("days") || "7", 10);
+        const stats = await getStats(Math.min(days, 30));
+        const html = generateDashboardHtml(stats);
+
+        res.writeHead(200, {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-cache",
+        });
+        res.end(html);
+      } catch (err) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: `Failed to generate dashboard: ${err instanceof Error ? err.message : String(err)}`,
+          }),
+        );
+      }
+      return;
+    }
+
+    // Stats API endpoint - returns JSON for programmatic access
+    if (req.url === "/stats" || req.url?.startsWith("/stats?")) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const days = parseInt(url.searchParams.get("days") || "7", 10);
+        const stats = await getStats(Math.min(days, 30));
+
+        res.writeHead(200, {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-cache",
+        });
+        res.end(JSON.stringify(stats, null, 2));
+      } catch (err) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: `Failed to get stats: ${err instanceof Error ? err.message : String(err)}`,
+          }),
+        );
+      }
+      return;
+    }
+
     // Only proxy paths starting with /v1
     if (!req.url?.startsWith("/v1")) {
       res.writeHead(404, { "Content-Type": "application/json" });
@@ -1135,7 +1183,10 @@ async function proxyRequest(
     const entry: UsageEntry = {
       timestamp: new Date().toISOString(),
       model: routingDecision.model,
+      tier: routingDecision.tier,
       cost: routingDecision.costEstimate,
+      baselineCost: routingDecision.baselineCost,
+      savings: routingDecision.savings,
       latencyMs: Date.now() - startTime,
     };
     logUsage(entry).catch(() => {});