feat: usage tracking and billing system for user pricing

[lancy]

Background

As VM0 grows, we need a billing system to monetize the platform. Users run agents that consume compute resources (sandbox execution time), and we need to track this usage and charge accordingly.

Current State

The platform already has foundational elements in place:

• Run duration tracking: startedAt and completedAt timestamps on agent runs, with execution_time_ms already calculated in the API
• User identity: Clerk-based authentication with scope system (personal/organization/system)
• Resource metrics: CPU, memory, and disk usage collected via Axiom (time-series data per run)
• Storage tracking: Size and file count per volume/artifact

What's Missing

• Usage aggregation (e.g., total run time per user per billing period)
• Billing/subscription data model
• Pricing configuration
• Payment processor integration
• Quota enforcement and usage limits

---

Requirements

Core Functionality

1. Usage Tracking

   • Track total execution duration per user per billing period
   • Aggregate run-level data into billable usage summaries
   • Provide users visibility into their usage

2. Billing Model

   • Support charging based on run duration (primary metric)
   • Flexible enough to add other metrics later (run count, storage, resources)
   • Handle billing periods (monthly)

3. User Scope

   • Start with individual user billing
   • Architecture should allow adding team/organization billing later

4. Usage Visibility

   • Users can see their current usage
   • Users can see their billing history

---

Acceptance Criteria

• Users can view their total run duration for the current billing period
• Usage data is aggregated and queryable per user per period
• System can calculate billable amounts based on usage
• Usage tracking does not impact run performance

---

User Scenarios

Scenario 1: User checks usage

A user wants to see how much compute time they've used this month. They can view a usage summary showing total run duration and estimated cost.

Scenario 2: End of billing period

At month end, the system calculates total usage for each user and generates billing records that can be used for invoicing.

Scenario 3: User approaches limit

If usage limits are implemented, users receive notification when approaching their quota.

---

Open Questions

1. What billing model to use? (pure usage-based vs subscription + overage vs tiered plans)
2. What granularity for duration tracking? (seconds vs minutes)
3. How to handle failed/timeout runs in billing?
4. Should there be a free tier? If so, what limits?
5. What payment processor to integrate with?

---

Scope Boundaries

In scope:

• Usage tracking and aggregation
• Billing data model
• Usage visibility for users

Out of scope (for initial version):

• Team/organization billing (future enhancement)
• Complex resource-based pricing (CPU/memory weighting)
• Real-time usage alerts

[lancy]

Research: How Other SaaS Services Handle Usage & Pricing

Based on research of major cloud providers (AWS, Vercel, Cloudflare, Railway, Render, Replicate, OpenAI, Anthropic), here are the key findings:

---

Pricing Model Patterns

Type	Providers	Primary Metric
GB-seconds	AWS Lambda	Memory × Duration
vCPU + Memory per second	Railway	Separate rates for CPU and RAM
Requests + CPU time	Cloudflare Workers	Dual metric
Invocations + Duration	Vercel	Per-call + time
Instance-hours	AWS EC2, Render	Fixed instance pricing
Tokens	OpenAI, Anthropic	Input/output separately

---

Billing Granularity

Provider	Granularity
AWS Lambda	Milliseconds
AWS EC2	Seconds (60s minimum)
Cloudflare Workers	Milliseconds (CPU time)
Railway	Seconds
Vercel	Per invocation
Replicate	Seconds

Observation: Modern services bill per-second or per-millisecond, not per-hour.

---

Free Tier Examples

Provider	Free Tier
AWS Lambda	1M requests + 400K GB-seconds/month
Cloudflare Workers	100K requests/day + 10ms CPU/invocation
Vercel	1M invocations + 100GB transfer
Railway	$5 trial credit (30 days)
Anthropic	$5 credits (no expiration)

---

Specific Pricing Examples

AWS Lambda:

• $0.20 per million requests
• $0.0000166667 per GB-second

Cloudflare Workers ($5/month minimum):

• 10M requests included, then $0.30 per million
• 30M CPU-ms included, then $0.02 per million ms

Railway (pure usage-based):

• Memory: $0.00000386 per GB/sec
• CPU: $0.00000772 per vCPU/sec

Replicate (AI models):

• CPU: $0.000025/sec ($0.09/hr)
• GPU A100: $0.001400/sec ($5.04/hr)

---

Usage Display Patterns

Dashboard Features:

1. Cost vs Activity views - Separate views for spending and usage metrics (OpenAI)
2. Per-service breakdown - Usage grouped by function/worker (Vercel, Cloudflare)
3. Time granularity - 1-minute to daily aggregates available
4. Filtering - By API key, project, or time period

Export Options:

• PDF invoices (Vercel)
• CSV data export (OpenAI, AWS)
• Programmatic Usage API (OpenAI)

Alerts:

• Spending threshold notifications
• Rate limit warnings
• Quota approaching alerts

---

Most Relevant Models for VM0

Given that VM0 runs agent sandboxes with configurable vCPU/memory:

1. Railway's model - vCPU + Memory per-second closely matches our sandbox resources
2. Cloudflare's model - Request count + CPU time is similar to run count + duration
3. Replicate's model - Per-second compute for AI workloads

---

Key Questions Informed by Research

1. Single vs dual metric?

   • Simple: Duration only (like early Lambda)
   • Complex: Duration + resource tier (like current Lambda GB-seconds)

2. Free tier structure?

   • Credit-based: $5 free credits (Anthropic, Railway trial)
   • Quota-based: X runs or Y minutes per month (AWS Lambda style)

3. Billing granularity?

   • Per-second seems standard for compute
   • Per-minute may be simpler to understand

4. Base subscription?

   • Pure usage-based: Railway, Replicate
   • Subscription + usage: Cloudflare ($5 min), Vercel Pro ($20 + usage)