Add enforced monthly spending limit with Spending tab and Overview meter

EfeAcar6431 · cursoragent · EfeAcar6431 · commit 4aab67487fa0 · 2026-06-22T19:09:26.000-04:00
- Settings gains a Spending tab mirroring the dashboard: monthly meter with
  editable limit, this-month / all-time / avg-per-run stats, and cost by
  model/provider
- Overview shows a Cursor-style "$spent / $limit" progress bar
- Default monthly cap is $50 when unset, and it's actually enforced: runs
  (chat + `coderouter run`) and loop start/resume are blocked once this
  month's account-wide spend reaches the cap (SpendingLimitError)

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/packages/app/src/pages/Overview.tsx b/packages/app/src/pages/Overview.tsx
@@ -1,16 +1,20 @@
 import React, { useEffect, useState } from 'react';
-import { api, type UsageReport } from '../lib/api';
+import { api, type SettingsReport, type UsageReport } from '../lib/api';
 import { Heatmap } from '../components/Heatmap';
 import { Section, Spinner, money } from '../components/common';
+import { DEFAULT_LIMIT_USD, SpendingProgress } from './Spending';
 
 export function OverviewPage(): React.ReactElement {
   const [data, setData] = useState<UsageReport | null>(null);
+  const [settings, setSettings] = useState<SettingsReport | null>(null);
   useEffect(() => {
     void api.usage().then(setData).catch(() => {});
+    void api.settings().then(setSettings).catch(() => {});
   }, []);
   if (!data) return <Spinner />;
   const t = data.totals;
   const h = data.highlights;
+  const limit = settings?.limits.monthlyUsd ?? DEFAULT_LIMIT_USD;
 
   return (
     <div>
@@ -21,6 +25,19 @@ export function OverviewPage(): React.ReactElement {
         <Big label="Projects" value={String(data.project.projectCount)} />
       </div>
 
+      <Section title="Monthly spend">
+        <div className="card">
+          <div className="mb-3 flex items-baseline justify-between">
+            <span className="text-sm text-muted">This month</span>
+            <span className="text-sm">
+              <span className="font-semibold">{money(t.monthCostUsd)}</span>
+              <span className="text-muted"> / {money(limit)}</span>
+            </span>
+          </div>
+          <SpendingProgress spent={t.monthCostUsd} limit={limit} />
+        </div>
+      </Section>
+
       <Section title="Activity">
         <div className="card">
           <Heatmap days={data.heatmap} />
diff --git a/packages/app/src/pages/SettingsArea.tsx b/packages/app/src/pages/SettingsArea.tsx
@@ -3,6 +3,7 @@ import { ArrowLeft } from 'lucide-react';
 import { Tabs } from '../components/common';
 import { SettingsPage } from './Settings';
 import { ModelsPage } from './Models';
+import { SpendingPage } from './Spending';
 
 /** Settings hub: provider/host configuration plus model tier preferences. */
 export function SettingsArea({ onBack }: { onBack?: () => void }): React.ReactElement {
@@ -22,11 +23,12 @@ export function SettingsArea({ onBack }: { onBack?: () => void }): React.ReactEl
         tabs={[
           { id: 'general', label: 'General' },
           { id: 'models', label: 'Models' },
+          { id: 'spending', label: 'Spending' },
         ]}
         active={tab}
         onChange={setTab}
       />
-      {tab === 'general' ? <SettingsPage /> : <ModelsPage />}
+      {tab === 'general' ? <SettingsPage /> : tab === 'models' ? <ModelsPage /> : <SpendingPage />}
     </div>
   );
 }
diff --git a/packages/app/src/pages/Spending.tsx b/packages/app/src/pages/Spending.tsx
@@ -0,0 +1,150 @@
+import React, { useEffect, useState } from 'react';
+import { api, type SettingsReport, type UsageReport } from '../lib/api';
+import { Section, Spinner, cls, money } from '../components/common';
+
+/** Default cap mirrored from the daemon (`DEFAULT_MONTHLY_LIMIT_USD`). */
+export const DEFAULT_LIMIT_USD = 50;
+
+/** A Cursor-style spend-vs-limit progress bar. */
+export function SpendingProgress({
+  spent,
+  limit,
+}: {
+  spent: number;
+  limit: number;
+}): React.ReactElement {
+  const pct = limit > 0 ? Math.min(100, (spent / limit) * 100) : 0;
+  const over = spent >= limit;
+  return (
+    <div>
+      <div className="h-2 w-full overflow-hidden rounded-full bg-panel2">
+        <div
+          className={cls('h-full rounded-full transition-all', over ? 'bg-bad' : 'bg-accent')}
+          style={{ width: `${Math.max(2, pct)}%` }}
+        />
+      </div>
+      <div className="mt-1.5 flex items-center justify-between text-xs">
+        <span className={cls(over ? 'text-bad' : 'text-muted')}>
+          {over ? 'Monthly limit reached' : `${money(Math.max(0, limit - spent))} remaining this month`}
+        </span>
+        <span className="text-muted">{Math.round(pct)}%</span>
+      </div>
+    </div>
+  );
+}
+
+export function SpendingPage(): React.ReactElement {
+  const [usage, setUsage] = useState<UsageReport | null>(null);
+  const [settings, setSettings] = useState<SettingsReport | null>(null);
+  const [draft, setDraft] = useState('');
+  const [saving, setSaving] = useState(false);
+
+  const load = (): void => {
+    void api.usage().then(setUsage).catch(() => {});
+    void api
+      .settings()
+      .then((s) => {
+        setSettings(s);
+        setDraft(String(s.limits.monthlyUsd ?? DEFAULT_LIMIT_USD));
+      })
+      .catch(() => {});
+  };
+  useEffect(load, []);
+
+  if (!usage || !settings) return <Spinner />;
+
+  const t = usage.totals;
+  const limit = settings.limits.monthlyUsd ?? DEFAULT_LIMIT_USD;
+  const spent = t.monthCostUsd;
+  const avgPerRun = t.runs > 0 ? t.costUsd / t.runs : 0;
+  const maxProvider = Math.max(1, ...usage.byProvider.map((b) => b.costUsd));
+
+  const save = async (): Promise<void> => {
+    const val = Number(draft);
+    setSaving(true);
+    try {
+      await api.setLimit(Number.isFinite(val) && val > 0 ? val : null);
+      load();
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div>
+      <div className="mb-5 flex items-baseline justify-between">
+        <h1 className="text-xl font-semibold">Spending</h1>
+        <span className="text-sm text-muted">{money(t.costUsd)} all-time</span>
+      </div>
+
+      {/* Monthly meter + limit editor */}
+      <div className="card mb-4">
+        <div className="flex flex-wrap items-start justify-between gap-4">
+          <div>
+            <div className="text-xs uppercase tracking-wide text-muted">Spending · {monthLabel(t.monthKey)}</div>
+            <div className="mt-1 text-3xl font-semibold">{money(spent)}</div>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="text-sm text-muted">Monthly limit $</span>
+            <input
+              type="number"
+              min={0}
+              step={1}
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              className="input w-28"
+              placeholder={String(DEFAULT_LIMIT_USD)}
+            />
+            <button onClick={() => void save()} disabled={saving} className="btn btn-primary">
+              {saving ? 'Saving…' : 'Save'}
+            </button>
+          </div>
+        </div>
+        <div className="mt-4">
+          <SpendingProgress spent={spent} limit={limit} />
+        </div>
+      </div>
+
+      {/* Stat cards */}
+      <div className="mb-6 grid grid-cols-1 gap-3 md:grid-cols-3">
+        <Stat label="This month" value={money(spent)} hint={monthLabel(t.monthKey)} />
+        <Stat label="All-time cost" value={money(t.costUsd)} hint={`${t.runs} runs`} />
+        <Stat label="Avg cost / run" value={money(avgPerRun)} hint="across all routes" />
+      </div>
+
+      <Section title="Cost by model / provider">
+        <div className="card space-y-3">
+          {usage.byProvider.length === 0 && <div className="text-sm text-muted">No spend recorded yet.</div>}
+          {usage.byProvider.map((b) => (
+            <div key={b.key}>
+              <div className="mb-1 flex items-center justify-between text-sm">
+                <span className="min-w-0 truncate">{b.label}</span>
+                <span className="shrink-0 text-muted">{money(b.costUsd)}</span>
+              </div>
+              <div className="h-1.5 w-full overflow-hidden rounded-full bg-panel2">
+                <div className="h-full rounded-full bg-accent" style={{ width: `${(b.costUsd / maxProvider) * 100}%` }} />
+              </div>
+            </div>
+          ))}
+        </div>
+      </Section>
+    </div>
+  );
+}
+
+function Stat({ label, value, hint }: { label: string; value: string; hint?: string }): React.ReactElement {
+  return (
+    <div className="card">
+      <div className="text-xs uppercase tracking-wide text-muted">{label}</div>
+      <div className="mt-1 text-2xl font-semibold">{value}</div>
+      {hint && <div className="mt-0.5 text-xs text-muted">{hint}</div>}
+    </div>
+  );
+}
+
+/** `YYYY-MM` → `June 2026`. */
+function monthLabel(monthKey: string): string {
+  const [y, m] = monthKey.split('-').map(Number);
+  if (!y || !m) return monthKey;
+  return new Date(y, m - 1, 1).toLocaleDateString(undefined, { month: 'long', year: 'numeric' });
+}
diff --git a/packages/cli/src/daemon/server.ts b/packages/cli/src/daemon/server.ts
@@ -16,6 +16,7 @@ import {
 } from './lockfile.js';
 import { handlePtyUpgrade } from './pty.js';
 import { getSupervisor } from './supervisor.js';
+import { assertWithinSpendingLimit } from '../spend.js';
 
 /**
  * CodeRouter daemon ("app-server").
@@ -481,6 +482,7 @@ async function handleLoops(
   if (method === 'POST') {
     switch (action) {
       case 'start':
+        await assertWithinSpendingLimit(project);
         await sup.start(project, loopId).catch((e) => {
           throw e;
         });
@@ -489,6 +491,7 @@ async function handleLoops(
         sup.pause(loopId);
         return reply(res, 200, { ok: true });
       case 'resume':
+        await assertWithinSpendingLimit(project);
         await sup.resume(project, loopId);
         return reply(res, 200, { ok: true });
       case 'stop':
diff --git a/packages/cli/src/runtime.ts b/packages/cli/src/runtime.ts
@@ -29,6 +29,7 @@ import type {
 import type { Report } from '@coderouter/core';
 import { spinnerProgress } from './ui/progress.js';
 import { getPreferredModels } from './ui/setup.js';
+import { assertWithinSpendingLimit } from './spend.js';
 
 export type ProgressAdapter = {
   notifier: ProgressNotifier;
@@ -166,6 +167,9 @@ export async function executeRun(opts: CliRunOpts): Promise<{
   output: ModeOutput;
   store: Store;
 }> {
+  // Enforce the monthly spending cap before doing any billable work.
+  await assertWithinSpendingLimit(opts.cwd);
+
   const { registry, router, store } = await buildExecutionEnv(opts.cwd);
   // Stable conversation id: the REPL passes one per session so turns
   // group into a single browsable chat; one-shot runs get a fresh id.
diff --git a/packages/cli/src/spend.ts b/packages/cli/src/spend.ts
@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { listProjects, openStore, resolveDbPath } from '@coderouter/core';
+import { getEffectiveSpendingLimit } from './ui/setup.js';
+
+/** `YYYY-MM` key for a timestamp in local time (matches the dashboard). */
+function localMonthKey(ts: number): string {
+  const d = new Date(ts);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * Total spend (USD) for the current calendar month across every CodeRouter
+ * project registered on this machine. Spending is account-wide because API
+ * keys and billing are account-wide, so the cap is enforced globally.
+ */
+export async function getMonthlySpendUsd(extraCwd?: string): Promise<number> {
+  const dbPaths = new Set<string>();
+  for (const p of listProjects()) dbPaths.add(p.dbPath);
+  if (extraCwd) {
+    const dp = resolveDbPath(extraCwd);
+    if (existsSync(dp)) dbPaths.add(dp);
+  }
+
+  const monthKey = localMonthKey(Date.now());
+  let total = 0;
+  for (const path of dbPaths) {
+    if (!existsSync(path)) continue;
+    const store = await openStore(path);
+    try {
+      for (const r of store.runs.list(5000)) {
+        if (localMonthKey(r.createdAt) === monthKey) total += r.costUsd;
+      }
+    } finally {
+      try {
+        store.db.close();
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+  return total;
+}
+
+/** Thrown when a run is blocked because the monthly spending cap is reached. */
+export class SpendingLimitError extends Error {
+  constructor(
+    public spentUsd: number,
+    public limitUsd: number,
+  ) {
+    super(
+      `Monthly spending limit reached: $${spentUsd.toFixed(2)} of $${limitUsd.toFixed(2)} used this month. ` +
+        `Raise or remove the cap in Settings → Spending to continue.`,
+    );
+    this.name = 'SpendingLimitError';
+  }
+}
+
+/**
+ * Throw `SpendingLimitError` if this month's spend already meets or exceeds
+ * the effective monthly cap. Call before starting any billable work.
+ */
+export async function assertWithinSpendingLimit(cwd?: string): Promise<void> {
+  const limit = getEffectiveSpendingLimit();
+  const spent = await getMonthlySpendUsd(cwd);
+  if (spent >= limit) throw new SpendingLimitError(spent, limit);
+}
diff --git a/packages/cli/src/ui/setup.ts b/packages/cli/src/ui/setup.ts
@@ -211,9 +211,16 @@ export function setHostEnabled(provider: HostProvider, enabled: boolean): void {
   else process.env[envName] = '1';
 }
 
+/**
+ * Default monthly spending cap (USD) enforced when the user hasn't set one.
+ * CodeRouter always has a cap so runaway agent loops can't quietly burn
+ * through an API budget.
+ */
+export const DEFAULT_MONTHLY_LIMIT_USD = 50;
+
 /**
  * Read the persisted monthly spending limit (USD). Returns `null` when
- * unset or invalid, meaning "no cap".
+ * unset or invalid, meaning "use the default cap".
  */
 export function getSpendingLimit(): { monthlyUsd: number | null } {
   try {
@@ -225,9 +232,18 @@ export function getSpendingLimit(): { monthlyUsd: number | null } {
   }
 }
 
+/**
+ * The monthly limit actually enforced: the user's value if set, else the
+ * default cap. Always a positive number — there is always a cap.
+ */
+export function getEffectiveSpendingLimit(): number {
+  const v = getSpendingLimit().monthlyUsd;
+  return typeof v === 'number' && v > 0 ? v : DEFAULT_MONTHLY_LIMIT_USD;
+}
+
 /**
  * Persist (or clear) the monthly spending limit. Passing `null` or a
- * non-positive number removes the cap.
+ * non-positive number removes the explicit cap (falling back to the default).
  */
 export function setSpendingLimit(monthlyUsd: number | null): void {
   let existing: CredentialsFile = {};
