Cost Monitoring & Alerts

LLM costs can spiral quickly when agents loop, users abuse the system, or a bug causes excessive API calls. CoFounder includes a built-in cost tracking system that lets you enforce budgets at the project, team, and individual user level. This lesson shows how to set it up and configure meaningful alerts.

CoFounder Cost Tracker

The @waymakerai/aicofounder-core package includes a cost tracker that records every LLM call with its token usage and calculated cost. It persists data to your Supabase database for querying and dashboards:

// lib/cost-tracker.ts
import { CostTracker } from '@waymakerai/aicofounder-core';
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

export const costTracker = new CostTracker({
  db: supabase,
  table: 'llm_costs',
  pricing: {
    'gpt-4o':              { input: 0.0025, output: 0.01 },
    'gpt-4o-mini':         { input: 0.00015, output: 0.0006 },
    'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
    'claude-haiku-3':      { input: 0.00025, output: 0.00125 },
  },
});

// Record a call
await costTracker.record({
  userId: 'user_123',
  provider: 'anthropic',
  model: 'claude-sonnet-4-20250514',
  inputTokens: 1500,
  outputTokens: 800,
  metadata: { agentId: 'support-agent', sessionId: 'sess_abc' },
});

// Query costs
const monthlyCost = await costTracker.getMonthlyCost();
const userCost = await costTracker.getUserCost('user_123', { period: '30d' });

Budget Enforcement

Budget enforcement prevents runaway costs by rejecting LLM calls once a threshold is reached. Configure budgets in your .cofounder.yml and enforce them in middleware:

// middleware/cost-guard.ts
import { costTracker } from '@/lib/cost-tracker';
import { env } from '@/lib/env';

export async function costGuard(userId: string): Promise<{
  allowed: boolean;
  reason?: string;
  remainingBudget?: number;
}> {
  // Check project-level monthly budget
  const monthlyCost = await costTracker.getMonthlyCost();
  if (monthlyCost >= env.COFOUNDER_BUDGET_MONTHLY_USD) {
    return {
      allowed: false,
      reason: 'Monthly project budget exceeded. Contact your administrator.',
    };
  }

  // Check per-user limit
  const userCost = await costTracker.getUserCost(userId, { period: '30d' });
  const userLimit = 10; // $10/user/month from .cofounder.yml
  if (userCost >= userLimit) {
    return {
      allowed: false,
      reason: 'Your monthly usage limit has been reached.',
      remainingBudget: 0,
    };
  }

  return {
    allowed: true,
    remainingBudget: userLimit - userCost,
  };
}

// Usage in an API route
import { costGuard } from '@/middleware/cost-guard';

export async function POST(req: Request) {
  const userId = await getUserId(req);
  const budget = await costGuard(userId);

  if (!budget.allowed) {
    return Response.json({ error: budget.reason }, { status: 429 });
  }

  // Proceed with agent execution...
}

Cost Dashboard with SQL

Build a cost dashboard by querying the llm_costs table directly. These SQL queries work with Supabase and can power a real-time admin dashboard:

-- Daily cost breakdown by model
SELECT
  DATE(created_at) AS day,
  model,
  COUNT(*) AS calls,
  SUM(input_tokens) AS total_input_tokens,
  SUM(output_tokens) AS total_output_tokens,
  SUM(cost_usd) AS total_cost
FROM llm_costs
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY day, model
ORDER BY day DESC, total_cost DESC;

-- Top 10 most expensive users this month
SELECT
  user_id,
  COUNT(*) AS total_calls,
  SUM(cost_usd) AS total_cost,
  AVG(cost_usd) AS avg_cost_per_call
FROM llm_costs
WHERE created_at >= DATE_TRUNC('month', NOW())
GROUP BY user_id
ORDER BY total_cost DESC
LIMIT 10;

-- Hourly cost trend (for spike detection)
SELECT
  DATE_TRUNC('hour', created_at) AS hour,
  SUM(cost_usd) AS hourly_cost,
  COUNT(*) AS call_count
FROM llm_costs
WHERE created_at >= NOW() - INTERVAL '24 hours'
GROUP BY hour
ORDER BY hour;

Alert Thresholds

Configure alerts at multiple levels to catch cost problems early. CoFounder supports alert thresholds as a percentage of your budget:

// lib/cost-alerts.ts
import { costTracker } from '@/lib/cost-tracker';

interface AlertThreshold {
  percent: number;
  channel: 'email' | 'slack' | 'pagerduty';
  severity: 'info' | 'warning' | 'critical';
}

const thresholds: AlertThreshold[] = [
  { percent: 50, channel: 'slack', severity: 'info' },
  { percent: 80, channel: 'slack', severity: 'warning' },
  { percent: 95, channel: 'pagerduty', severity: 'critical' },
];

export async function checkCostAlerts(budgetUsd: number) {
  const currentCost = await costTracker.getMonthlyCost();
  const percentUsed = (currentCost / budgetUsd) * 100;

  for (const threshold of thresholds) {
    if (percentUsed >= threshold.percent) {
      await sendAlert({
        severity: threshold.severity,
        channel: threshold.channel,
        message: `LLM cost alert: ${percentUsed.toFixed(1)}% of monthly budget used ($${currentCost.toFixed(2)} / $${budgetUsd})`,
      });
    }
  }
}

// Run via cron job: every hour
// See vercel.json crons or a scheduled Lambda