Merge remote-tracking branch 'public-gh/master' into paperclip-subissues

* public-gh/master:
  Fix budget incident resolution edge cases
  Fix agent budget tab routing
  Fix budget auth and monthly spend rollups
  Harden budget enforcement and migration startup
  Add budget tabs and sidebar budget indicators
  feat(costs): add billing, quota, and budget control plane
  refactor(quota): move provider quota logic into adapter layer, add unit tests
  fix(costs): replace non-null map assertions with nullish coalescing, clarify weekData guard
  fix(costs): guard byProject against duplicate null keys, memoize ProviderQuotaCard row aggregations
  fix(costs): align byAgent run filter to startedAt, tighten providerTabItems memo deps, stabilize byProject row keys
  feat(costs): add agent model breakdown, harden date validation, sync CostByProject type, fix quota threshold and tab-gated queries
  fix(costs): harden company auth check, fix frozen date memo, hide empty quota rows
  fix(costs): guard routes, fix DST ranges, sync provider state, wire live updates
  feat(costs): consolidate /usage into /costs with Spend + Providers tabs
  feat(usage): add subscription quota windows per provider on /usage page
  address greptile review: per-provider deficit notch, startedAt filter, weekRange refresh, deduplicate providerDisplayName
  feat(ui): add resource and usage dashboard (/usage route)

# Conflicts:
#	packages/db/src/migration-runtime.ts
#	packages/db/src/migrations/meta/0031_snapshot.json
#	packages/db/src/migrations/meta/_journal.json

packages/shared/src/constants.ts

@@ -137,6 +137,9 @@ export const PROJECT_STATUSES = [
 ] as const;
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
 
+export const PAUSE_REASONS = ["manual", "budget", "system"] as const;
+export type PauseReason = (typeof PAUSE_REASONS)[number];
+
 export const PROJECT_COLORS = [
   "#6366f1", // indigo
   "#8b5cf6", // violet
@@ -150,7 +153,7 @@ export const PROJECT_COLORS = [
   "#3b82f6", // blue
 ] as const;
 
-export const APPROVAL_TYPES = ["hire_agent", "approve_ceo_strategy"] as const;
+export const APPROVAL_TYPES = ["hire_agent", "approve_ceo_strategy", "budget_override_required"] as const;
 export type ApprovalType = (typeof APPROVAL_TYPES)[number];
 
 export const APPROVAL_STATUSES = [
@@ -173,6 +176,73 @@ export type SecretProvider = (typeof SECRET_PROVIDERS)[number];
 export const STORAGE_PROVIDERS = ["local_disk", "s3"] as const;
 export type StorageProvider = (typeof STORAGE_PROVIDERS)[number];
 
+export const BILLING_TYPES = [
+  "metered_api",
+  "subscription_included",
+  "subscription_overage",
+  "credits",
+  "fixed",
+  "unknown",
+] as const;
+export type BillingType = (typeof BILLING_TYPES)[number];
+
+export const FINANCE_EVENT_KINDS = [
+  "inference_charge",
+  "platform_fee",
+  "credit_purchase",
+  "credit_refund",
+  "credit_expiry",
+  "byok_fee",
+  "gateway_overhead",
+  "log_storage_charge",
+  "logpush_charge",
+  "provisioned_capacity_charge",
+  "training_charge",
+  "custom_model_import_charge",
+  "custom_model_storage_charge",
+  "manual_adjustment",
+] as const;
+export type FinanceEventKind = (typeof FINANCE_EVENT_KINDS)[number];
+
+export const FINANCE_DIRECTIONS = ["debit", "credit"] as const;
+export type FinanceDirection = (typeof FINANCE_DIRECTIONS)[number];
+
+export const FINANCE_UNITS = [
+  "input_token",
+  "output_token",
+  "cached_input_token",
+  "request",
+  "credit_usd",
+  "credit_unit",
+  "model_unit_minute",
+  "model_unit_hour",
+  "gb_month",
+  "train_token",
+  "unknown",
+] as const;
+export type FinanceUnit = (typeof FINANCE_UNITS)[number];
+
+export const BUDGET_SCOPE_TYPES = ["company", "agent", "project"] as const;
+export type BudgetScopeType = (typeof BUDGET_SCOPE_TYPES)[number];
+
+export const BUDGET_METRICS = ["billed_cents"] as const;
+export type BudgetMetric = (typeof BUDGET_METRICS)[number];
+
+export const BUDGET_WINDOW_KINDS = ["calendar_month_utc", "lifetime"] as const;
+export type BudgetWindowKind = (typeof BUDGET_WINDOW_KINDS)[number];
+
+export const BUDGET_THRESHOLD_TYPES = ["soft", "hard"] as const;
+export type BudgetThresholdType = (typeof BUDGET_THRESHOLD_TYPES)[number];
+
+export const BUDGET_INCIDENT_STATUSES = ["open", "resolved", "dismissed"] as const;
+export type BudgetIncidentStatus = (typeof BUDGET_INCIDENT_STATUSES)[number];
+
+export const BUDGET_INCIDENT_RESOLUTION_ACTIONS = [
+  "keep_paused",
+  "raise_budget_and_resume",
+] as const;
+export type BudgetIncidentResolutionAction = (typeof BUDGET_INCIDENT_RESOLUTION_ACTIONS)[number];
+
 export const HEARTBEAT_INVOCATION_SOURCES = [
   "timer",
   "assignment",

packages/shared/src/index.ts

@@ -13,11 +13,22 @@ export {
   GOAL_LEVELS,
   GOAL_STATUSES,
   PROJECT_STATUSES,
+  PAUSE_REASONS,
   PROJECT_COLORS,
   APPROVAL_TYPES,
   APPROVAL_STATUSES,
   SECRET_PROVIDERS,
   STORAGE_PROVIDERS,
+  BILLING_TYPES,
+  FINANCE_EVENT_KINDS,
+  FINANCE_DIRECTIONS,
+  FINANCE_UNITS,
+  BUDGET_SCOPE_TYPES,
+  BUDGET_METRICS,
+  BUDGET_WINDOW_KINDS,
+  BUDGET_THRESHOLD_TYPES,
+  BUDGET_INCIDENT_STATUSES,
+  BUDGET_INCIDENT_RESOLUTION_ACTIONS,
   HEARTBEAT_INVOCATION_SOURCES,
   HEARTBEAT_RUN_STATUSES,
   WAKEUP_TRIGGER_DETAILS,
@@ -61,10 +72,21 @@ export {
   type GoalLevel,
   type GoalStatus,
   type ProjectStatus,
+  type PauseReason,
   type ApprovalType,
   type ApprovalStatus,
   type SecretProvider,
   type StorageProvider,
+  type BillingType,
+  type FinanceEventKind,
+  type FinanceDirection,
+  type FinanceUnit,
+  type BudgetScopeType,
+  type BudgetMetric,
+  type BudgetWindowKind,
+  type BudgetThresholdType,
+  type BudgetIncidentStatus,
+  type BudgetIncidentResolutionAction,
   type HeartbeatInvocationSource,
   type HeartbeatRunStatus,
   type WakeupTriggerDetail,
@@ -140,9 +162,24 @@ export type {
   Goal,
   Approval,
   ApprovalComment,
+  BudgetPolicy,
+  BudgetPolicySummary,
+  BudgetIncident,
+  BudgetOverview,
+  BudgetPolicyUpsertInput,
+  BudgetIncidentResolutionInput,
   CostEvent,
   CostSummary,
   CostByAgent,
+  CostByProviderModel,
+  CostByBiller,
+  CostByAgentModel,
+  CostWindowSpendRow,
+  CostByProject,
+  FinanceEvent,
+  FinanceSummary,
+  FinanceByBiller,
+  FinanceByKind,
   HeartbeatRun,
   HeartbeatRunEvent,
   AgentRuntimeState,
@@ -198,6 +235,8 @@ export type {
   PluginJobRecord,
   PluginJobRunRecord,
   PluginWebhookDeliveryRecord,
+  QuotaWindow,
+  ProviderQuotaResult,
 } from "./types/index.js";
 
 export {
@@ -268,11 +307,15 @@ export {
   type CreateGoal,
   type UpdateGoal,
   createApprovalSchema,
+  upsertBudgetPolicySchema,
+  resolveBudgetIncidentSchema,
   resolveApprovalSchema,
   requestApprovalRevisionSchema,
   resubmitApprovalSchema,
   addApprovalCommentSchema,
   type CreateApproval,
+  type UpsertBudgetPolicy,
+  type ResolveBudgetIncident,
   type ResolveApproval,
   type RequestApprovalRevision,
   type ResubmitApproval,
@@ -288,6 +331,7 @@ export {
   type RotateSecret,
   type UpdateSecret,
   createCostEventSchema,
+  createFinanceEventSchema,
   updateBudgetSchema,
   createAssetImageMetadataSchema,
   createCompanyInviteSchema,
@@ -298,6 +342,7 @@ export {
   updateMemberPermissionsSchema,
   updateUserCompanyAccessSchema,
   type CreateCostEvent,
+  type CreateFinanceEvent,
   type UpdateBudget,
   type CreateAssetImageMetadata,
   type CreateCompanyInvite,

packages/shared/src/types/agent.ts

@@ -1,5 +1,6 @@
 import type {
   AgentAdapterType,
+  PauseReason,
   AgentRole,
   AgentStatus,
 } from "../constants.js";
@@ -24,6 +25,8 @@ export interface Agent {
   runtimeConfig: Record<string, unknown>;
   budgetMonthlyCents: number;
   spentMonthlyCents: number;
+  pauseReason: PauseReason | null;
+  pausedAt: Date | null;
   permissions: AgentPermissions;
   lastHeartbeatAt: Date | null;
   metadata: Record<string, unknown> | null;

packages/shared/src/types/budget.ts

@@ -0,0 +1,99 @@
+import type {
+  BudgetIncidentResolutionAction,
+  BudgetIncidentStatus,
+  BudgetMetric,
+  BudgetScopeType,
+  BudgetThresholdType,
+  BudgetWindowKind,
+  PauseReason,
+} from "../constants.js";
+
+export interface BudgetPolicy {
+  id: string;
+  companyId: string;
+  scopeType: BudgetScopeType;
+  scopeId: string;
+  metric: BudgetMetric;
+  windowKind: BudgetWindowKind;
+  amount: number;
+  warnPercent: number;
+  hardStopEnabled: boolean;
+  notifyEnabled: boolean;
+  isActive: boolean;
+  createdByUserId: string | null;
+  updatedByUserId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface BudgetPolicySummary {
+  policyId: string;
+  companyId: string;
+  scopeType: BudgetScopeType;
+  scopeId: string;
+  scopeName: string;
+  metric: BudgetMetric;
+  windowKind: BudgetWindowKind;
+  amount: number;
+  observedAmount: number;
+  remainingAmount: number;
+  utilizationPercent: number;
+  warnPercent: number;
+  hardStopEnabled: boolean;
+  notifyEnabled: boolean;
+  isActive: boolean;
+  status: "ok" | "warning" | "hard_stop";
+  paused: boolean;
+  pauseReason: PauseReason | null;
+  windowStart: Date;
+  windowEnd: Date;
+}
+
+export interface BudgetIncident {
+  id: string;
+  companyId: string;
+  policyId: string;
+  scopeType: BudgetScopeType;
+  scopeId: string;
+  scopeName: string;
+  metric: BudgetMetric;
+  windowKind: BudgetWindowKind;
+  windowStart: Date;
+  windowEnd: Date;
+  thresholdType: BudgetThresholdType;
+  amountLimit: number;
+  amountObserved: number;
+  status: BudgetIncidentStatus;
+  approvalId: string | null;
+  approvalStatus: string | null;
+  resolvedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface BudgetOverview {
+  companyId: string;
+  policies: BudgetPolicySummary[];
+  activeIncidents: BudgetIncident[];
+  pausedAgentCount: number;
+  pausedProjectCount: number;
+  pendingApprovalCount: number;
+}
+
+export interface BudgetPolicyUpsertInput {
+  scopeType: BudgetScopeType;
+  scopeId: string;
+  metric?: BudgetMetric;
+  windowKind?: BudgetWindowKind;
+  amount: number;
+  warnPercent?: number;
+  hardStopEnabled?: boolean;
+  notifyEnabled?: boolean;
+  isActive?: boolean;
+}
+
+export interface BudgetIncidentResolutionInput {
+  action: BudgetIncidentResolutionAction;
+  amount?: number;
+  decisionNote?: string | null;
+}

packages/shared/src/types/company.ts

@@ -1,10 +1,12 @@
-import type { CompanyStatus } from "../constants.js";
+import type { CompanyStatus, PauseReason } from "../constants.js";
 
 export interface Company {
   id: string;
   name: string;
   description: string | null;
   status: CompanyStatus;
+  pauseReason: PauseReason | null;
+  pausedAt: Date | null;
   issuePrefix: string;
   issueCounter: number;
   budgetMonthlyCents: number;

packages/shared/src/types/cost.ts

@@ -1,3 +1,5 @@
+import type { BillingType } from "../constants.js";
+
 export interface CostEvent {
   id: string;
   companyId: string;
@@ -5,10 +7,14 @@ export interface CostEvent {
   issueId: string | null;
   projectId: string | null;
   goalId: string | null;
+  heartbeatRunId: string | null;
   billingCode: string | null;
   provider: string;
+  biller: string;
+  billingType: BillingType;
   model: string;
   inputTokens: number;
+  cachedInputTokens: number;
   outputTokens: number;
   costCents: number;
   occurredAt: Date;
@@ -28,9 +34,80 @@ export interface CostByAgent {
   agentStatus: string | null;
   costCents: number;
   inputTokens: number;
+  cachedInputTokens: number;
   outputTokens: number;
   apiRunCount: number;
   subscriptionRunCount: number;
+  subscriptionCachedInputTokens: number;
   subscriptionInputTokens: number;
   subscriptionOutputTokens: number;
 }
+
+export interface CostByProviderModel {
+  provider: string;
+  biller: string;
+  billingType: BillingType;
+  model: string;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  apiRunCount: number;
+  subscriptionRunCount: number;
+  subscriptionCachedInputTokens: number;
+  subscriptionInputTokens: number;
+  subscriptionOutputTokens: number;
+}
+
+export interface CostByBiller {
+  biller: string;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  apiRunCount: number;
+  subscriptionRunCount: number;
+  subscriptionCachedInputTokens: number;
+  subscriptionInputTokens: number;
+  subscriptionOutputTokens: number;
+  providerCount: number;
+  modelCount: number;
+}
+
+/** per-agent breakdown by provider + model, for identifying token-hungry agents */
+export interface CostByAgentModel {
+  agentId: string;
+  agentName: string | null;
+  provider: string;
+  biller: string;
+  billingType: BillingType;
+  model: string;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}
+
+/** spend per provider for a fixed rolling time window */
+export interface CostWindowSpendRow {
+  provider: string;
+  biller: string;
+  /** duration label, e.g. "5h", "24h", "7d" */
+  window: string;
+  /** rolling window duration in hours */
+  windowHours: number;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}
+
+/** cost attributed to a project via heartbeat run → activity log → issue → project chain */
+export interface CostByProject {
+  projectId: string | null;
+  projectName: string | null;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}

packages/shared/src/types/dashboard.ts

@@ -18,4 +18,10 @@ export interface DashboardSummary {
     monthUtilizationPercent: number;
   };
   pendingApprovals: number;
+  budgets: {
+    activeIncidents: number;
+    pendingApprovals: number;
+    pausedAgents: number;
+    pausedProjects: number;
+  };
 }

packages/shared/src/types/finance.ts

@@ -0,0 +1,60 @@
+import type { AgentAdapterType, FinanceDirection, FinanceEventKind, FinanceUnit } from "../constants.js";
+
+export interface FinanceEvent {
+  id: string;
+  companyId: string;
+  agentId: string | null;
+  issueId: string | null;
+  projectId: string | null;
+  goalId: string | null;
+  heartbeatRunId: string | null;
+  costEventId: string | null;
+  billingCode: string | null;
+  description: string | null;
+  eventKind: FinanceEventKind;
+  direction: FinanceDirection;
+  biller: string;
+  provider: string | null;
+  executionAdapterType: AgentAdapterType | null;
+  pricingTier: string | null;
+  region: string | null;
+  model: string | null;
+  quantity: number | null;
+  unit: FinanceUnit | null;
+  amountCents: number;
+  currency: string;
+  estimated: boolean;
+  externalInvoiceId: string | null;
+  metadataJson: Record<string, unknown> | null;
+  occurredAt: Date;
+  createdAt: Date;
+}
+
+export interface FinanceSummary {
+  companyId: string;
+  debitCents: number;
+  creditCents: number;
+  netCents: number;
+  estimatedDebitCents: number;
+  eventCount: number;
+}
+
+export interface FinanceByBiller {
+  biller: string;
+  debitCents: number;
+  creditCents: number;
+  netCents: number;
+  estimatedDebitCents: number;
+  eventCount: number;
+  kindCount: number;
+}
+
+export interface FinanceByKind {
+  eventKind: FinanceEventKind;
+  debitCents: number;
+  creditCents: number;
+  netCents: number;
+  estimatedDebitCents: number;
+  eventCount: number;
+  billerCount: number;
+}

packages/shared/src/types/index.ts

@@ -47,6 +47,14 @@ export type {
 } from "./issue.js";
 export type { Goal } from "./goal.js";
 export type { Approval, ApprovalComment } from "./approval.js";
+export type {
+  BudgetPolicy,
+  BudgetPolicySummary,
+  BudgetIncident,
+  BudgetOverview,
+  BudgetPolicyUpsertInput,
+  BudgetIncidentResolutionInput,
+} from "./budget.js";
 export type {
   SecretProvider,
   SecretVersionSelector,
@@ -57,7 +65,8 @@ export type {
   CompanySecret,
   SecretProviderDescriptor,
 } from "./secrets.js";
-export type { CostEvent, CostSummary, CostByAgent } from "./cost.js";
+export type { CostEvent, CostSummary, CostByAgent, CostByProviderModel, CostByBiller, CostByAgentModel, CostWindowSpendRow, CostByProject } from "./cost.js";
+export type { FinanceEvent, FinanceSummary, FinanceByBiller, FinanceByKind } from "./finance.js";
 export type {
   HeartbeatRun,
   HeartbeatRunEvent,
@@ -77,6 +86,7 @@ export type {
   JoinRequest,
   InstanceUserRoleGrant,
 } from "./access.js";
+export type { QuotaWindow, ProviderQuotaResult } from "./quota.js";
 export type {
   CompanyPortabilityInclude,
   CompanyPortabilitySecretRequirement,

packages/shared/src/types/project.ts

@@ -1,4 +1,4 @@
-import type { ProjectStatus } from "../constants.js";
+import type { PauseReason, ProjectStatus } from "../constants.js";
 import type { ProjectExecutionWorkspacePolicy, WorkspaceRuntimeService } from "./workspace-runtime.js";
 
 export type ProjectWorkspaceSourceType = "local_path" | "git_repo" | "remote_managed" | "non_git_path";
@@ -60,6 +60,8 @@ export interface Project {
   leadAgentId: string | null;
   targetDate: string | null;
   color: string | null;
+  pauseReason: PauseReason | null;
+  pausedAt: Date | null;
   executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null;
   codebase: ProjectCodebase;
   workspaces: ProjectWorkspace[];

packages/shared/src/types/quota.ts

@@ -0,0 +1,26 @@
+/** a single rate-limit or usage window returned by a provider quota API */
+export interface QuotaWindow {
+  /** human label, e.g. "5h", "7d", "Sonnet 7d", "Credits" */
+  label: string;
+  /** percent of the window already consumed (0-100), null when not reported */
+  usedPercent: number | null;
+  /** iso timestamp when this window resets, null when not reported */
+  resetsAt: string | null;
+  /** free-form value label for credit-style windows, e.g. "$4.20 remaining" */
+  valueLabel: string | null;
+  /** optional supporting text, e.g. reset details or provider-specific notes */
+  detail?: string | null;
+}
+
+/** result for one provider from the quota-windows endpoint */
+export interface ProviderQuotaResult {
+  /** provider slug, e.g. "anthropic", "openai" */
+  provider: string;
+  /** source label when the provider reports where the quota data came from */
+  source?: string | null;
+  /** true when the fetch succeeded and windows is populated */
+  ok: boolean;
+  /** error message when ok is false */
+  error?: string;
+  windows: QuotaWindow[];
+}

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,
@@ -137,6 +144,11 @@ export {
   type UpdateBudget,
 } from "./cost.js";
 
+export {
+  createFinanceEventSchema,
+  type CreateFinanceEvent,
+} from "./finance.js";
+
 export {
   createAssetImageMetadataSchema,
   type CreateAssetImageMetadata,