Cost & Usage Tracking

packages/billing/src/
  index.ts        # public exports
  rates.ts        # CREDIT_RATES constant
  balance.ts      # getOrCreateCreditBalance, reserveCredits, consumeCredits, releaseCredits, getCreditCost

createContentWorker("email-writer", { creditType: "email_newsletter" })

┌──────────────────────────────────────────────────────────┐
│  Tenant monthly cap                                      │  ← Platform-wide ceiling per client
│    └── Agent monthly cap (per role)                      │  ← Monthly ceiling per agent type
│           └── Campaign budget cap                        │  ← Per-campaign spending limit
│                  └── Per-task cost cap                   │  ← Single execution ceiling
└──────────────────────────────────────────────────────────┘

const MODEL_PRICING: Record<string, { inputPer1M: number; outputPer1M: number }> = {
  'claude-sonnet-4-6':          { inputPer1M: 3.00,   outputPer1M: 15.00  },
  'claude-opus-4-6':            { inputPer1M: 15.00,  outputPer1M: 75.00  },
  'claude-haiku-4-5-20251001':  { inputPer1M: 0.25,   outputPer1M: 1.25   },
  'gpt-4o':                     { inputPer1M: 2.50,   outputPer1M: 10.00  },
  'gpt-4o-mini':                { inputPer1M: 0.15,   outputPer1M: 0.60   },
  'gemma3:4b':                  { inputPer1M: 0,       outputPer1M: 0      }, // local
  'llama3.2':                   { inputPer1M: 0,       outputPer1M: 0      }, // local
  'mistral':                    { inputPer1M: 0,       outputPer1M: 0      }, // local
};
 
function calculateCost(model: string, inputTokens: number, outputTokens: number): number {
  const p = MODEL_PRICING[model] ?? { inputPer1M: 0, outputPer1M: 0 };
  return (inputTokens / 1_000_000) * p.inputPer1M
       + (outputTokens / 1_000_000) * p.outputPer1M;
}

await db.insert(llmCalls).values({
  id:           crypto.randomUUID(),
  taskRunId:    taskRun.id,
  tenantId:     tenant.id,
  agentRole:    agentConfig.role,
  sessionId:    session?.id ?? null,
  model,
  promptHash:   sha256(fullPrompt),    // no raw prompt stored — privacy
  responseHash: sha256(responseText),
  inputTokens,
  outputTokens,
  costUsd:      calculateCost(model, inputTokens, outputTokens),
  durationMs,
  createdAt:    new Date(),
});

await db.transaction(async (tx) => {
  // 1. Campaign running total
  await tx.update(campaigns)
    .set({ totalCostUsd: sql`total_cost_usd + ${costUsd}` })
    .where(eq(campaigns.id, campaignId));
 
  // 2. Agent monthly spend (upsert — row created on first spend of the month)
  await tx.insert(agentMonthlySpend)
    .values({ tenantId, agentRole, month: startOfMonth(), totalCostUsd: costUsd })
    .onConflictDoUpdate({
      target: [agentMonthlySpend.tenantId, agentMonthlySpend.agentRole, agentMonthlySpend.month],
      set: { totalCostUsd: sql`total_cost_usd + ${costUsd}` },
    });
 
  // 3. Tenant monthly spend
  await tx.update(tenants)
    .set({ currentMonthSpendUsd: sql`current_month_spend_usd + ${costUsd}` })
    .where(eq(tenants.id, tenantId));
});

let runningCost = 0;
 
for await (const event of executor.execute(request)) {
  if (event.type === 'text_delta') {
    runningCost = estimateCostFromStreamedTokens(model, estimatedInputTokens, streamedOutputTokens);
 
    if (agentConfig.limits.maxCostUsdPerTask && runningCost > agentConfig.limits.maxCostUsdPerTask) {
      executor.abort();
      throw new CostCapExceededError(`Task cost cap of $${agentConfig.limits.maxCostUsdPerTask} exceeded`);
    }
  }
  yield event;
}

async function checkCampaignBudget(campaignId: string, estimatedCallCost: number): Promise<void> {
  const campaign = await db.query.campaigns.findFirst({ where: eq(campaigns.id, campaignId) });
 
  if (!campaign.budgetCapUsd) return;  // no cap set
 
  if (campaign.totalCostUsd + estimatedCallCost > campaign.budgetCapUsd) {
    await db.update(campaigns)
      .set({ status: 'paused', pauseReason: 'budget_exceeded' })
      .where(eq(campaigns.id, campaignId));
    await drainCampaignQueueJobs(campaignId);
    await notifyBudgetBreached({ level: 'campaign', campaign });
    throw new BudgetCapExceededError(`Campaign budget of $${campaign.budgetCapUsd} would be exceeded`);
  }
}

async function checkAgentMonthlyBudget(
  tenantId: string,
  agentRole: AgentRole,
  estimatedCallCost: number,
): Promise<'ok' | 'warning' | 'exceeded'> {
  const config = await db.query.agentConfigs.findFirst({
    where: and(eq(agentConfigs.tenantId, tenantId), eq(agentConfigs.role, agentRole)),
  });
 
  if (!config.monthlyBudgetCapUsd) return 'ok';
 
  const spend = await db.query.agentMonthlySpend.findFirst({
    where: and(
      eq(agentMonthlySpend.tenantId, tenantId),
      eq(agentMonthlySpend.agentRole, agentRole),
      eq(agentMonthlySpend.month, startOfMonth()),
    ),
  });
 
  const currentSpend = spend?.totalCostUsd ?? 0;
  const usagePct = currentSpend / config.monthlyBudgetCapUsd;
 
  if (currentSpend + estimatedCallCost > config.monthlyBudgetCapUsd) {
    await pauseAgent(tenantId, agentRole, 'monthly_budget_exceeded');
    await notifyBudgetBreached({ level: 'agent', agentRole, tenantId });
    throw new BudgetCapExceededError(`Agent ${agentRole} monthly budget of $${config.monthlyBudgetCapUsd} exceeded`);
  }
 
  if (usagePct >= 0.8) return 'warning';  // caller injects prompt warning (see below)
  return 'ok';
}

async function checkTenantMonthlyBudget(tenantId: string, estimatedCallCost: number): Promise<void> {
  const tenant = await db.query.tenants.findFirst({ where: eq(tenants.id, tenantId) });
 
  if (!tenant.monthlySpendCapUsd) return;
 
  const usagePct = tenant.currentMonthSpendUsd / tenant.monthlySpendCapUsd;
 
  if (tenant.currentMonthSpendUsd + estimatedCallCost > tenant.monthlySpendCapUsd) {
    // Pause ALL agent queues for this tenant
    await pauseAllAgentsForTenant(tenantId, 'tenant_monthly_budget_exceeded');
    await notifyBudgetBreached({ level: 'tenant', tenantId });
    throw new BudgetCapExceededError(`Tenant monthly budget of $${tenant.monthlySpendCapUsd} exceeded`);
  }
 
  if (usagePct >= 0.8) {
    // One-time alert — deduplicated per day
    await sendBudgetWarning({ level: 'tenant', tenantId, usagePct });
  }
}

async function buildSystemPromptWithBudgetWarning(
  baseSystemPrompt: string,
  tenantId: string,
  agentRole: AgentRole,
): Promise<string> {
  const budgetStatus = await checkAgentMonthlyBudget(tenantId, agentRole, 0);
 
  if (budgetStatus !== 'warning') return baseSystemPrompt;
 
  const spend = await getAgentMonthlySpend(tenantId, agentRole);
  const config = await getAgentConfig(tenantId, agentRole);
  const pct = Math.round((spend / config.monthlyBudgetCapUsd) * 100);
 
  const warning = `
⚠️ BUDGET NOTICE: You have used ${pct}% of your monthly token budget for this client.
You are approaching your limit. For this task:
- Be concise in your responses
- Skip optional research or elaboration steps
- Focus only on the core deliverable
- Avoid making unnecessary tool calls
`;
 
  return warning + '\n\n' + baseSystemPrompt;
}

// Budget alert check — BullMQ repeatable job, runs every 15 minutes
async function checkBudgetAlerts(): Promise<void> {
  // Campaign-level
  const campaignsWithCaps = await db.query.campaigns.findMany({
    where: and(isNotNull(campaigns.budgetCapUsd), eq(campaigns.status, 'active')),
  });
 
  for (const campaign of campaignsWithCaps) {
    const usagePct = campaign.totalCostUsd / campaign.budgetCapUsd;
    if (usagePct >= 0.8 && usagePct < 1.0) {
      await sendAlertOnce(`campaign:${campaign.id}:80pct`, {
        text: `⚠️ Campaign "${campaign.name}" is at ${Math.round(usagePct * 100)}% of its budget ($${campaign.totalCostUsd.toFixed(2)} / $${campaign.budgetCapUsd})`,
      });
    }
  }
 
  // Tenant-level
  const tenantsWithCaps = await db.query.tenants.findMany({
    where: isNotNull(tenants.monthlySpendCapUsd),
  });
 
  for (const tenant of tenantsWithCaps) {
    const usagePct = tenant.currentMonthSpendUsd / tenant.monthlySpendCapUsd;
    if (usagePct >= 0.8 && usagePct < 1.0) {
      await sendAlertOnce(`tenant:${tenant.id}:80pct:${startOfMonth()}`, {
        text: `⚠️ Tenant "${tenant.name}" is at ${Math.round(usagePct * 100)}% of their monthly LLM budget`,
        recipient: tenant.adminEmail,
      });
    }
  }
}

// Registered as a repeatable job at startup
await budgetResetQueue.add('monthly-budget-reset', {}, {
  repeat: { pattern: '0 0 1 * *' },  // 1st of every month at midnight UTC
});
 
// Processor
async function monthlyBudgetReset(): Promise<void> {
  await db.transaction(async (tx) => {
    // 1. Reset all tenant monthly spend counters
    await tx.update(tenants)
      .set({ currentMonthSpendUsd: 0 });
 
    // 2. Reset agent monthly spend table (keep rows for history, set to 0 for current month)
    //    New month's rows will be created on first spend — nothing to reset
 
    // 3. Resume campaigns paused by budget
    await tx.update(campaigns)
      .set({ status: 'active', pauseReason: null })
      .where(eq(campaigns.pauseReason, 'budget_exceeded'));
 
    // 4. Resume agents paused by monthly budget
    await tx.update(agentConfigs)
      .set({ status: 'active', pauseReason: null })
      .where(eq(agentConfigs.pauseReason, 'monthly_budget_exceeded'));
  });
 
  // Re-enqueue any campaigns that were waiting for budget reset
  await requeuePausedCampaignTasks();
 
  await logger.info('Monthly budget reset complete');
}

export const agentMonthlySpend = pgTable('agent_monthly_spend', {
  id:           uuid('id').primaryKey().defaultRandom(),
  tenantId:     uuid('tenant_id').notNull().references(() => tenants.id),
  agentRole:    text('agent_role').notNull(),
  month:        date('month').notNull(),          // always 1st of month: '2026-04-01'
  totalCostUsd: numeric('total_cost_usd', { precision: 10, scale: 6 }).notNull().default('0'),
  updatedOn:    timestamp('updated_on').notNull().defaultNow(),
}, (t) => ({
  uniqueIdx: uniqueIndex('agent_monthly_spend_unique').on(t.tenantId, t.agentRole, t.month),
  tenantIdx: index('agent_monthly_spend_tenant_idx').on(t.tenantId),
}));

// Added to the agent_configs table
monthlyBudgetCapUsd: numeric('monthly_budget_cap_usd', { precision: 10, scale: 2 }),
// null = no monthly cap for this agent

1. checkTenantMonthlyBudget(tenantId, estimatedCost)
   → Throws if tenant monthly cap exceeded
   → Warning if ≥80% (Slack alert, deduplicated)

2. checkAgentMonthlyBudget(tenantId, agentRole, estimatedCost)
   → Throws if agent monthly cap exceeded (agent paused for month)
   → Returns 'warning' if ≥80%

3. checkCampaignBudget(campaignId, estimatedCost)
   → Throws if campaign cap exceeded (campaign paused)

4. Build system prompt
   → If step 2 returned 'warning': prepend budget notice to system prompt
   → Agent receives warning; self-limits accordingly

5. Dispatch task → execute
   → Per-task cap enforced mid-stream (abort if exceeded)

SELECT
  c.id, c.name, cl.name AS client_name,
  COALESCE(SUM(l.cost_usd), 0) AS total_cost_usd,
  SUM(l.input_tokens)           AS total_input_tokens,
  SUM(l.output_tokens)          AS total_output_tokens,
  COUNT(l.id)                   AS total_calls
FROM campaigns c
LEFT JOIN clients cl ON cl.id = c.client_id
LEFT JOIN tasks t    ON t.campaign_id = c.id
LEFT JOIN task_runs tr ON tr.task_id = t.id
LEFT JOIN llm_calls l  ON l.task_run_id = tr.id
GROUP BY c.id, cl.name;

SELECT
  ams.agent_role,
  ams.month,
  ams.total_cost_usd,
  ac.monthly_budget_cap_usd,
  ROUND((ams.total_cost_usd / NULLIF(ac.monthly_budget_cap_usd, 0)) * 100, 1) AS pct_used
FROM agent_monthly_spend ams
JOIN agent_configs ac ON ac.tenant_id = ams.tenant_id AND ac.role = ams.agent_role
WHERE ams.tenant_id = :tenantId
ORDER BY ams.month DESC, ams.total_cost_usd DESC;

SELECT
  t.id, t.name, t.plan,
  t.current_month_spend_usd,
  t.monthly_spend_cap_usd,
  ROUND((t.current_month_spend_usd / NULLIF(t.monthly_spend_cap_usd, 0)) * 100, 1) AS pct_used
FROM tenants t
WHERE t.deleted_on IS NULL
ORDER BY t.current_month_spend_usd DESC;

packages/agent-engine/
├── src/
│   ├── pricing.ts         # MODEL_PRICING, calculateCost()
│   ├── budget.ts          # checkTenantMonthlyBudget(), checkAgentMonthlyBudget(),
│   │                      # checkCampaignBudget(), pauseAgent(), resumeAgent()
│   ├── budget-warning.ts  # buildSystemPromptWithBudgetWarning() — 80% prompt injection
│   └── budget-reset.ts    # monthlyBudgetReset() — BullMQ cron processor

apps/api/
└── src/
    └── routes/
        └── costs.ts       # API endpoints for Cost Dashboard queries