feat: per-guild AI spend tracking and daily budget cap (#200)

* feat: add per-guild AI spend tracking and daily budget cap (#167)

- Add guildSpend.js utility with getGuildSpend() and checkGuildBudget()
- Gate triage evaluations when guild exceeds dailyBudgetUsd
- Log warning at 80% budget utilization (Phase 3)
- Post alert to moderation log channel on budget exceeded (Phase 3)
- Add triage.dailyBudgetUsd: 10 default to config.json

* test: add tests for guild spend tracking and triage budget gate (#167)

- 13 unit tests for getGuildSpend() and checkGuildBudget()
- 8 integration tests for triage budget gate behavior:
  - allows evaluation when budget is ok or no budget configured
  - logs warning at 80% utilization, continues evaluation
  - blocks evaluation when budget is exceeded
  - sends alert to moderation log channel on exceeded budget
  - non-fatal when budget check errors (evaluation continues)

* style: fix biome import ordering and formatting in budget gate files

* fix(triage): throttle budget-exceeded alert to prevent spam

Track lastBudgetAlertAt per guild in a module-level Map. Only post
the moderation log channel alert if no alert has been sent within
BUDGET_ALERT_COOLDOWN_MS (1 hour). Prevents repeated 'AI spend cap
reached' messages flooding the mod log on every evaluation attempt
while a guild is over budget.

Resolves review thread PRRT_kwDORICdSM5xdS6p

* fix(triage): ensure clearEvaluatedMessages runs on budget gate return

Move the budget gate block inside the outer try block so the
finally { clearEvaluatedMessages(channelId, snapshotIds) } clause
always executes, even when we return early because the guild has
exhausted its daily budget. Previously the early return escaped the
try/finally entirely, leaving snapshot message IDs in the channel
buffer where they could be reprocessed on the next evaluation tick.

Resolves review thread PRRT_kwDORICdSM5xdS6v

---------

Co-authored-by: Bill Chirico <[email protected]>

Author: BillChirico

config.json

@@ -42,7 +42,8 @@
     "debugFooter": true,
     "debugFooterLevel": "verbose",
     "moderationLogChannel": "1473219285651292201",
-    "statusReactions": true
+    "statusReactions": true,
+    "dailyBudgetUsd": 10
   },
   "welcome": {
     "enabled": true,

src/modules/triage.js

@@ -17,6 +17,8 @@
 
 import { debug, info, error as logError, warn } from '../logger.js';
 import { loadPrompt, promptPath } from '../prompts/index.js';
+import { fetchChannelCached } from '../utils/discordCache.js';
+import { checkGuildBudget } from '../utils/guildSpend.js';
 import { safeSend } from '../utils/safeSend.js';
 import { CLIProcess, CLIProcessError } from './cli-process.js';
 import { buildMemoryContext, extractAndStoreMemories } from './memory.js';
@@ -66,6 +68,14 @@ let classifierProcess = null;
 /** @type {CLIProcess|null} */
 let responderProcess = null;
 
+// ── Budget alert throttle ────────────────────────────────────────────────────
+// Track the last time a budget-exceeded alert was posted per guild so we don't
+// spam the moderation log channel on every evaluation attempt.
+/** @type {Map<string, number>} guildId → timestamp of last alert (ms) */
+const budgetAlertSentAt = new Map();
+/** Minimum gap between budget-exceeded alerts for the same guild (1 hour). */
+const BUDGET_ALERT_COOLDOWN_MS = 60 * 60 * 1_000;
+
 // ── Two-step CLI evaluation ──────────────────────────────────────────────────
 
 /**
@@ -333,6 +343,63 @@ async function evaluateAndRespond(channelId, snapshot, evalConfig, evalClient) {
   const snapshotIds = new Set(snapshot.map((m) => m.messageId));
 
   try {
+    // ── Guild daily budget gate ─────────────────────────────────────────────
+    // Skip evaluation if the guild has exhausted its daily AI spend cap.
+    // This prevents runaway costs from high-volume guilds.
+    // NOTE: kept inside the try block so the finally { clearEvaluatedMessages }
+    // always runs — even when we return early due to budget exhaustion.
+    const dailyBudgetUsd = evalConfig.triage?.dailyBudgetUsd;
+    if (dailyBudgetUsd != null && dailyBudgetUsd > 0) {
+      try {
+        const ch = await fetchChannelCached(evalClient, channelId);
+        const guildId = ch?.guildId;
+        if (guildId) {
+          const budget = await checkGuildBudget(guildId, dailyBudgetUsd);
+          if (budget.status === 'exceeded') {
+            warn('Guild daily AI budget exceeded — skipping triage evaluation', {
+              guildId,
+              channelId,
+              spend: budget.spend,
+              budget: budget.budget,
+            });
+            // Post a throttled alert to the moderation log channel — at most once per
+            // BUDGET_ALERT_COOLDOWN_MS — to avoid spamming on every evaluation attempt.
+            const logChannelId = evalConfig.triage?.moderationLogChannel;
+            if (logChannelId) {
+              const now = Date.now();
+              const lastAlert = budgetAlertSentAt.get(guildId) ?? 0;
+              if (now - lastAlert >= BUDGET_ALERT_COOLDOWN_MS) {
+                budgetAlertSentAt.set(guildId, now);
+                fetchChannelCached(evalClient, logChannelId)
+                  .then((logCh) => {
+                    if (logCh) {
+                      return safeSend(
+                        logCh,
+                        `⚠️ **AI spend cap reached** for guild \`${guildId}\` — daily budget of $${budget.budget.toFixed(2)} exceeded (spent $${budget.spend.toFixed(4)}). Triage evaluations are paused until the window resets.`,
+                      );
+                    }
+                  })
+                  .catch(() => {});
+              }
+            }
+            return;
+          }
+          if (budget.status === 'warning') {
+            warn('Guild approaching daily AI budget limit', {
+              guildId,
+              channelId,
+              spend: budget.spend,
+              budget: budget.budget,
+              pct: Math.round(budget.pct * 100),
+            });
+          }
+        }
+      } catch (budgetErr) {
+        // Non-fatal: if budget check errors, allow evaluation to continue
+        debug('Guild budget check failed (non-fatal)', { channelId, error: budgetErr?.message });
+      }
+    }
+
     // Step 1: Classify
     const classResult = await runClassification(channelId, snapshot, evalConfig, evalClient);
     if (!classResult) return;

src/utils/guildSpend.js

@@ -0,0 +1,72 @@
+/**
+ * Per-guild AI spend tracking and enforcement utilities.
+ *
+ * Queries the `ai_usage` table to compute cumulative spend for a guild within a
+ * configurable time window (default: 24 hours).  Used by the triage module to
+ * gate evaluations when a guild exceeds its daily AI budget.
+ */
+
+import { getPool } from '../db.js';
+import { warn } from '../logger.js';
+
+/**
+ * Query cumulative AI spend for a guild within a rolling time window.
+ *
+ * Returns 0 when the database pool is unavailable, when guildId is falsy, or
+ * when no rows match.
+ *
+ * @param {string} guildId - Discord guild ID.
+ * @param {number} [windowMs=86400000] - Rolling window in milliseconds (default: 24 h).
+ * @returns {Promise<number>} Total spend in USD for the window period.
+ */
+export async function getGuildSpend(guildId, windowMs = 24 * 60 * 60 * 1000) {
+  if (!guildId) return 0;
+
+  let pool;
+  try {
+    pool = getPool();
+  } catch {
+    return 0;
+  }
+
+  try {
+    const since = new Date(Date.now() - windowMs);
+    const { rows } = await pool.query(
+      'SELECT COALESCE(SUM(cost_usd), 0) AS total FROM ai_usage WHERE guild_id = $1 AND created_at >= $2',
+      [guildId, since],
+    );
+    return parseFloat(rows[0]?.total ?? 0);
+  } catch (err) {
+    warn('getGuildSpend query failed', { guildId, error: err?.message });
+    return 0;
+  }
+}
+
+/**
+ * Check whether a guild has exceeded (or is approaching) its configured daily AI budget.
+ *
+ * Returns a structured result so callers can decide how to act:
+ * - 'exceeded'  — spend >= dailyBudgetUsd (block evaluation)
+ * - 'warning'   — spend >= 80% of dailyBudgetUsd (log a warning, continue)
+ * - 'ok'        — under 80% (no action needed)
+ *
+ * @param {string} guildId - Discord guild ID.
+ * @param {number} dailyBudgetUsd - Configured budget cap in USD.
+ * @param {number} [windowMs=86400000] - Rolling window in milliseconds (default: 24 h).
+ * @returns {Promise<{status: 'ok'|'warning'|'exceeded', spend: number, budget: number, pct: number}>}
+ */
+export async function checkGuildBudget(guildId, dailyBudgetUsd, windowMs = 24 * 60 * 60 * 1000) {
+  const spend = await getGuildSpend(guildId, windowMs);
+  const pct = dailyBudgetUsd > 0 ? spend / dailyBudgetUsd : 0;
+
+  let status;
+  if (pct >= 1) {
+    status = 'exceeded';
+  } else if (pct >= 0.8) {
+    status = 'warning';
+  } else {
+    status = 'ok';
+  }
+
+  return { status, spend, budget: dailyBudgetUsd, pct };
+}