feat(costs): add billing, quota, and budget control plane

packages/shared/src/validators/budget.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import {
+  BUDGET_INCIDENT_RESOLUTION_ACTIONS,
+  BUDGET_METRICS,
+  BUDGET_SCOPE_TYPES,
+  BUDGET_WINDOW_KINDS,
+} from "../constants.js";
+
+export const upsertBudgetPolicySchema = z.object({
+  scopeType: z.enum(BUDGET_SCOPE_TYPES),
+  scopeId: z.string().uuid(),
+  metric: z.enum(BUDGET_METRICS).optional().default("billed_cents"),
+  windowKind: z.enum(BUDGET_WINDOW_KINDS).optional().default("calendar_month_utc"),
+  amount: z.number().int().nonnegative(),
+  warnPercent: z.number().int().min(1).max(99).optional().default(80),
+  hardStopEnabled: z.boolean().optional().default(true),
+  notifyEnabled: z.boolean().optional().default(true),
+  isActive: z.boolean().optional().default(true),
+});
+
+export type UpsertBudgetPolicy = z.infer<typeof upsertBudgetPolicySchema>;
+
+export const resolveBudgetIncidentSchema = z.object({
+  action: z.enum(BUDGET_INCIDENT_RESOLUTION_ACTIONS),
+  amount: z.number().int().nonnegative().optional(),
+  decisionNote: z.string().optional().nullable(),
+}).superRefine((value, ctx) => {
+  if (value.action === "raise_budget_and_resume" && typeof value.amount !== "number") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "amount is required when raising a budget",
+      path: ["amount"],
+    });
+  }
+});
+
+export type ResolveBudgetIncident = z.infer<typeof resolveBudgetIncidentSchema>;

packages/shared/src/validators/cost.ts

@@ -1,18 +1,26 @@
 import { z } from "zod";
+import { BILLING_TYPES } from "../constants.js";
 
 export const createCostEventSchema = z.object({
   agentId: z.string().uuid(),
   issueId: z.string().uuid().optional().nullable(),
   projectId: z.string().uuid().optional().nullable(),
   goalId: z.string().uuid().optional().nullable(),
+  heartbeatRunId: z.string().uuid().optional().nullable(),
   billingCode: z.string().optional().nullable(),
   provider: z.string().min(1),
+  biller: z.string().min(1).optional(),
+  billingType: z.enum(BILLING_TYPES).optional().default("unknown"),
   model: z.string().min(1),
   inputTokens: z.number().int().nonnegative().optional().default(0),
+  cachedInputTokens: z.number().int().nonnegative().optional().default(0),
   outputTokens: z.number().int().nonnegative().optional().default(0),
   costCents: z.number().int().nonnegative(),
   occurredAt: z.string().datetime(),
-});
+}).transform((value) => ({
+  ...value,
+  biller: value.biller ?? value.provider,
+}));
 
 export type CreateCostEvent = z.infer<typeof createCostEventSchema>;
 

packages/shared/src/validators/finance.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { AGENT_ADAPTER_TYPES, FINANCE_DIRECTIONS, FINANCE_EVENT_KINDS, FINANCE_UNITS } from "../constants.js";
+
+export const createFinanceEventSchema = z.object({
+  agentId: z.string().uuid().optional().nullable(),
+  issueId: z.string().uuid().optional().nullable(),
+  projectId: z.string().uuid().optional().nullable(),
+  goalId: z.string().uuid().optional().nullable(),
+  heartbeatRunId: z.string().uuid().optional().nullable(),
+  costEventId: z.string().uuid().optional().nullable(),
+  billingCode: z.string().optional().nullable(),
+  description: z.string().max(500).optional().nullable(),
+  eventKind: z.enum(FINANCE_EVENT_KINDS),
+  direction: z.enum(FINANCE_DIRECTIONS).optional().default("debit"),
+  biller: z.string().min(1),
+  provider: z.string().min(1).optional().nullable(),
+  executionAdapterType: z.enum(AGENT_ADAPTER_TYPES).optional().nullable(),
+  pricingTier: z.string().min(1).optional().nullable(),
+  region: z.string().min(1).optional().nullable(),
+  model: z.string().min(1).optional().nullable(),
+  quantity: z.number().int().nonnegative().optional().nullable(),
+  unit: z.enum(FINANCE_UNITS).optional().nullable(),
+  amountCents: z.number().int().nonnegative(),
+  currency: z.string().length(3).optional().default("USD"),
+  estimated: z.boolean().optional().default(false),
+  externalInvoiceId: z.string().optional().nullable(),
+  metadataJson: z.record(z.string(), z.unknown()).optional().nullable(),
+  occurredAt: z.string().datetime(),
+}).transform((value) => ({
+  ...value,
+  currency: value.currency.toUpperCase(),
+}));
+
+export type CreateFinanceEvent = z.infer<typeof createFinanceEventSchema>;

packages/shared/src/validators/index.ts

@@ -1,3 +1,10 @@
+export {
+  upsertBudgetPolicySchema,
+  resolveBudgetIncidentSchema,
+  type UpsertBudgetPolicy,
+  type ResolveBudgetIncident,
+} from "./budget.js";
+
 export {
   createCompanySchema,
   updateCompanySchema,
@@ -121,6 +128,11 @@ export {
   type UpdateBudget,
 } from "./cost.js";
 
+export {
+  createFinanceEventSchema,
+  type CreateFinanceEvent,
+} from "./finance.js";
+
 export {
   createAssetImageMetadataSchema,
   type CreateAssetImageMetadata,