feat(billing): record function sandbox usage

Author: Bill Leoutsakos

apps/sim/app/api/webhooks/outbox/process/route.ts

@@ -8,6 +8,7 @@ import { verifyCronAuth } from '@/lib/auth/internal'
 import { enterpriseOwnerClaimOutboxHandlers } from '@/lib/billing/enterprise-owner-claim'
 import { enterpriseIssuanceOutboxHandlers } from '@/lib/billing/enterprise-provisioning'
 import { membershipBillingOutboxHandlers } from '@/lib/billing/organizations/membership-reconciliation'
+import { sandboxUsageOutboxHandlers } from '@/lib/billing/sandbox-usage-outbox'
 import { billingOutboxHandlers } from '@/lib/billing/webhooks/outbox-handlers'
 import { processOutboxEvents } from '@/lib/core/outbox/service'
 import { generateRequestId } from '@/lib/core/utils/request'
@@ -29,6 +30,7 @@ const handlers = {
   ...adminMemberOperationOutboxHandlers,
   ...billingOutboxHandlers,
   ...membershipBillingOutboxHandlers,
+  ...sandboxUsageOutboxHandlers,
   ...enterpriseIssuanceOutboxHandlers,
   ...enterpriseOwnerClaimOutboxHandlers,
   ...invitationMigrationOutboxHandlers,

apps/sim/lib/billing/sandbox-pricing.test.ts

@@ -0,0 +1,51 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, expect, it } from 'vitest'
+import { createSandboxPricingSnapshot, priceSandboxUsage } from '@/lib/billing/sandbox-pricing'
+
+const STARTED_AT = new Date('2026-08-27T12:00:00.000Z')
+const ONE_HOUR_LATER = new Date('2026-08-27T13:00:00.000Z')
+
+describe('sandbox pricing', () => {
+  it.each([
+    ['e2b', 0.1656],
+    ['daytona', 0.16668],
+  ] as const)('prices one hour of the %s Function profile', (provider, expectedRawCost) => {
+    const priced = priceSandboxUsage(
+      createSandboxPricingSnapshot(provider, 1),
+      STARTED_AT,
+      ONE_HOUR_LATER,
+      ONE_HOUR_LATER
+    )
+
+    expect(priced.durationMs).toBe(3_600_000)
+    expect(priced.rawCost).toBeCloseTo(expectedRawCost, 10)
+    expect(priced.billedCost).toBe(expectedRawCost)
+  })
+
+  it('applies the multiplier once and rounds the billed cost to eight decimals', () => {
+    const priced = priceSandboxUsage(
+      createSandboxPricingSnapshot('e2b', 2.5),
+      STARTED_AT,
+      new Date(STARTED_AT.getTime() + 1234),
+      ONE_HOUR_LATER
+    )
+
+    expect(priced.billedCost).toBe(Number.parseFloat((priced.rawCost * 2.5).toFixed(8)))
+  })
+
+  it('caps billable duration at the provider expiry', () => {
+    const expiresAt = new Date(STARTED_AT.getTime() + 15_000)
+    const priced = priceSandboxUsage(
+      createSandboxPricingSnapshot('daytona', 1),
+      STARTED_AT,
+      ONE_HOUR_LATER,
+      expiresAt
+    )
+
+    expect(priced.durationMs).toBe(15_000)
+    expect(priced.sandboxSeconds).toBe(15)
+  })
+})

apps/sim/lib/billing/sandbox-pricing.ts

@@ -0,0 +1,154 @@
+import { getCostMultiplier } from '@/lib/core/config/env-flags'
+import {
+  FUNCTION_DAYTONA_DISK_GB,
+  FUNCTION_SANDBOX_CPU_COUNT,
+  FUNCTION_SANDBOX_MEMORY_GB,
+} from '@/lib/execution/remote-sandbox/function-resources'
+import type { SandboxProviderId } from '@/lib/execution/remote-sandbox/types'
+
+const PRICING_VERIFIED_AT = '2026-08-27' as const
+const E2B_CPU_USD_PER_VCPU_SECOND = 0.000014
+const E2B_MEMORY_USD_PER_GIB_SECOND = 0.0000045
+const DAYTONA_CPU_USD_PER_VCPU_SECOND = 0.0504 / 3600
+const DAYTONA_MEMORY_USD_PER_GIB_SECOND = 0.0162 / 3600
+const DAYTONA_DISK_USD_PER_GIB_SECOND = 0.000108 / 3600
+
+export interface SandboxResourceProfile {
+  vcpu: number
+  memoryGiB: number
+  diskGiB: number
+}
+
+export interface SandboxUnitRates {
+  cpuUsdPerVcpuSecond: number
+  memoryUsdPerGiBSecond: number
+  diskUsdPerGiBSecond: number
+}
+
+export interface SandboxPricingSnapshot {
+  version: 1
+  provider: SandboxProviderId
+  verifiedAt: typeof PRICING_VERIFIED_AT
+  multiplier: number
+  resources: SandboxResourceProfile
+  rates: SandboxUnitRates
+}
+
+export interface PricedSandboxUsage {
+  durationMs: number
+  sandboxSeconds: number
+  vcpuSeconds: number
+  memoryGiBSeconds: number
+  diskGiBSeconds: number
+  rawCost: number
+  billedCost: number
+}
+
+const PRICING_BY_PROVIDER: Record<
+  SandboxProviderId,
+  Pick<SandboxPricingSnapshot, 'resources' | 'rates'>
+> = {
+  e2b: {
+    resources: {
+      vcpu: FUNCTION_SANDBOX_CPU_COUNT,
+      memoryGiB: FUNCTION_SANDBOX_MEMORY_GB,
+      diskGiB: 0,
+    },
+    rates: {
+      cpuUsdPerVcpuSecond: E2B_CPU_USD_PER_VCPU_SECOND,
+      memoryUsdPerGiBSecond: E2B_MEMORY_USD_PER_GIB_SECOND,
+      diskUsdPerGiBSecond: 0,
+    },
+  },
+  daytona: {
+    resources: {
+      vcpu: FUNCTION_SANDBOX_CPU_COUNT,
+      memoryGiB: FUNCTION_SANDBOX_MEMORY_GB,
+      diskGiB: FUNCTION_DAYTONA_DISK_GB,
+    },
+    rates: {
+      cpuUsdPerVcpuSecond: DAYTONA_CPU_USD_PER_VCPU_SECOND,
+      memoryUsdPerGiBSecond: DAYTONA_MEMORY_USD_PER_GIB_SECOND,
+      diskUsdPerGiBSecond: DAYTONA_DISK_USD_PER_GIB_SECOND,
+    },
+  },
+}
+
+function roundCost(value: number): number {
+  return Number.parseFloat(value.toFixed(8))
+}
+
+function assertFiniteNonNegative(value: number, field: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`Sandbox pricing ${field} must be a finite non-negative number`)
+  }
+}
+
+export function createSandboxPricingSnapshot(
+  provider: SandboxProviderId,
+  multiplier = getCostMultiplier()
+): SandboxPricingSnapshot {
+  assertFiniteNonNegative(multiplier, 'multiplier')
+  const pricing = PRICING_BY_PROVIDER[provider]
+  return {
+    version: 1,
+    provider,
+    verifiedAt: PRICING_VERIFIED_AT,
+    multiplier,
+    resources: { ...pricing.resources },
+    rates: { ...pricing.rates },
+  }
+}
+
+export function assertSandboxPricingSnapshot(value: unknown): SandboxPricingSnapshot {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Sandbox pricing snapshot must be an object')
+  }
+  const snapshot = value as Partial<SandboxPricingSnapshot>
+  if (snapshot.version !== 1 || (snapshot.provider !== 'e2b' && snapshot.provider !== 'daytona')) {
+    throw new Error('Sandbox pricing snapshot version or provider is invalid')
+  }
+  if (snapshot.verifiedAt !== PRICING_VERIFIED_AT) {
+    throw new Error('Sandbox pricing snapshot verification date is invalid')
+  }
+  if (!snapshot.resources || !snapshot.rates) {
+    throw new Error('Sandbox pricing snapshot resources and rates are required')
+  }
+  assertFiniteNonNegative(snapshot.multiplier ?? Number.NaN, 'multiplier')
+  assertFiniteNonNegative(snapshot.resources.vcpu, 'resources.vcpu')
+  assertFiniteNonNegative(snapshot.resources.memoryGiB, 'resources.memoryGiB')
+  assertFiniteNonNegative(snapshot.resources.diskGiB, 'resources.diskGiB')
+  assertFiniteNonNegative(snapshot.rates.cpuUsdPerVcpuSecond, 'rates.cpuUsdPerVcpuSecond')
+  assertFiniteNonNegative(snapshot.rates.memoryUsdPerGiBSecond, 'rates.memoryUsdPerGiBSecond')
+  assertFiniteNonNegative(snapshot.rates.diskUsdPerGiBSecond, 'rates.diskUsdPerGiBSecond')
+  return snapshot as SandboxPricingSnapshot
+}
+
+export function priceSandboxUsage(
+  pricingValue: SandboxPricingSnapshot,
+  startedAt: Date,
+  terminatedAt: Date,
+  expiresAt: Date
+): PricedSandboxUsage {
+  const pricing = assertSandboxPricingSnapshot(pricingValue)
+  const effectiveEndMs = Math.min(terminatedAt.getTime(), expiresAt.getTime())
+  const durationMs = Math.max(0, effectiveEndMs - startedAt.getTime())
+  const sandboxSeconds = durationMs / 1000
+  const vcpuSeconds = sandboxSeconds * pricing.resources.vcpu
+  const memoryGiBSeconds = sandboxSeconds * pricing.resources.memoryGiB
+  const diskGiBSeconds = sandboxSeconds * pricing.resources.diskGiB
+  const rawCost =
+    vcpuSeconds * pricing.rates.cpuUsdPerVcpuSecond +
+    memoryGiBSeconds * pricing.rates.memoryUsdPerGiBSecond +
+    diskGiBSeconds * pricing.rates.diskUsdPerGiBSecond
+
+  return {
+    durationMs,
+    sandboxSeconds,
+    vcpuSeconds,
+    memoryGiBSeconds,
+    diskGiBSeconds,
+    rawCost,
+    billedCost: roundCost(rawCost * pricing.multiplier),
+  }
+}

apps/sim/lib/billing/sandbox-usage-outbox.test.ts

@@ -0,0 +1,153 @@
+/**
+ * @vitest-environment node
+ */
+
+import { usageLog } from '@sim/db/schema'
+import { dbChainMockFns, queueTableRows, resetDbChainMock } from '@sim/testing'
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockRecordUsage, mockTerminateById, mockThresholdBilling } = vi.hoisted(() => ({
+  mockRecordUsage: vi.fn(),
+  mockTerminateById: vi.fn(),
+  mockThresholdBilling: vi.fn(),
+}))
+
+vi.mock('@/lib/billing/core/usage-log', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@/lib/billing/core/usage-log')>()
+  return { ...original, recordUsage: mockRecordUsage }
+})
+vi.mock('@/lib/billing/threshold-billing', () => ({
+  checkAndBillPayerOverageThreshold: mockThresholdBilling,
+}))
+vi.mock('@/lib/core/config/env-flags', () => ({
+  getCostMultiplier: vi.fn(() => 1),
+  isBillingEnabled: false,
+}))
+vi.mock('@/lib/execution/remote-sandbox/provider', () => ({
+  getSandboxProvider: vi.fn(() => ({ terminateById: mockTerminateById })),
+}))
+
+import { createSandboxPricingSnapshot } from '@/lib/billing/sandbox-pricing'
+import {
+  SANDBOX_USAGE_OUTBOX_EVENT_TYPE,
+  type SandboxUsageOutboxPayloadV1,
+  sandboxUsageOutboxHandlers,
+} from '@/lib/billing/sandbox-usage-outbox'
+import type { OutboxEventContext } from '@/lib/core/outbox/service'
+
+const context: OutboxEventContext = {
+  eventId: 'event-1',
+  eventType: SANDBOX_USAGE_OUTBOX_EVENT_TYPE,
+  attempts: 0,
+  maxAttempts: 10,
+  signal: new AbortController().signal,
+  checkpointPayload: vi.fn(),
+}
+
+function payload(overrides: Partial<SandboxUsageOutboxPayloadV1> = {}) {
+  const base: SandboxUsageOutboxPayloadV1 = {
+    version: 1,
+    provider: 'e2b',
+    providerSandboxId: 'sandbox-1',
+    sandboxKind: 'code',
+    providerRequestedAt: '2026-08-27T12:00:00.000Z',
+    providerReadyAt: '2026-08-27T12:00:01.000Z',
+    providerExpiresAt: '2026-08-27T12:05:00.000Z',
+    terminationRequestedAt: '2026-08-27T12:00:10.000Z',
+    terminatedAt: '2026-08-27T12:00:10.000Z',
+    outcome: 'success',
+    cleanupStatus: 'terminated',
+    workspaceId: 'workspace-1',
+    workflowId: 'workflow-1',
+    executionId: 'execution-1',
+    billingAttribution: {
+      actorUserId: 'user-1',
+      workspaceId: 'workspace-1',
+      organizationId: null,
+      billedAccountUserId: 'user-1',
+      billingEntity: { type: 'user', id: 'user-1' },
+      billingPeriod: {
+        start: '2026-08-01T00:00:00.000Z',
+        end: '2026-09-01T00:00:00.000Z',
+      },
+      payerSubscription: null,
+    },
+    pricing: createSandboxPricingSnapshot('e2b', 1),
+  }
+  return { ...base, ...overrides }
+}
+
+async function runHandler(value: SandboxUsageOutboxPayloadV1): Promise<void> {
+  await sandboxUsageOutboxHandlers[SANDBOX_USAGE_OUTBOX_EVENT_TYPE](value, context)
+}
+
+afterAll(resetDbChainMock)
+
+describe('sandbox usage outbox finalizer', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+    queueTableRows(usageLog, [{ cost: '0.02' }])
+    mockRecordUsage.mockResolvedValue(undefined)
+    mockTerminateById.mockResolvedValue('terminated')
+  })
+
+  it('records an attributed Code sandbox ledger event and refreshes execution cost', async () => {
+    await runHandler(payload())
+
+    expect(mockRecordUsage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 'user-1',
+        workspaceId: 'workspace-1',
+        workflowId: 'workflow-1',
+        executionId: 'execution-1',
+        tx: expect.anything(),
+        entries: [
+          expect.objectContaining({
+            category: 'tool',
+            source: 'workflow',
+            description: 'Code sandbox',
+            sourceReference: 'sandbox:e2b:sandbox-1',
+          }),
+        ],
+      })
+    )
+    expect(dbChainMockFns.execute).toHaveBeenCalledOnce()
+    expect(dbChainMockFns.update).toHaveBeenCalled()
+  })
+
+  it('terminates and checkpoints a sandbox whose terminal timestamp is missing', async () => {
+    await runHandler(
+      payload({
+        terminationRequestedAt: undefined,
+        terminatedAt: undefined,
+        outcome: undefined,
+        cleanupStatus: 'active',
+      })
+    )
+
+    expect(mockTerminateById).toHaveBeenCalledWith('sandbox-1')
+    expect(context.checkpointPayload).toHaveBeenCalledWith(
+      expect.objectContaining({ cleanupStatus: 'terminated', terminatedAt: expect.any(String) })
+    )
+    expect(mockRecordUsage).toHaveBeenCalledOnce()
+  })
+
+  it('propagates transient provider failures so the generic outbox retries', async () => {
+    mockTerminateById.mockRejectedValueOnce(new Error('provider unavailable'))
+
+    await expect(
+      runHandler(payload({ terminatedAt: undefined, cleanupStatus: 'pending_reconciliation' }))
+    ).rejects.toThrow('provider unavailable')
+    expect(mockRecordUsage).not.toHaveBeenCalled()
+  })
+
+  it('uses the same ledger event key when finalization is replayed', async () => {
+    await runHandler(payload())
+    await runHandler(payload())
+
+    const firstEventKey = mockRecordUsage.mock.calls[0][0].entries[0].eventKey
+    const secondEventKey = mockRecordUsage.mock.calls[1][0].entries[0].eventKey
+    expect(firstEventKey).toBe(secondEventKey)
+  })
+})