feat(cloud): enforce host governance budgets

packages/cloud-platform/cloud/governance.py

@@ -10,6 +10,14 @@ class TaskSubmissionPolicyError(PermissionError):
     """Raised when a human user's policy disallows a task submission."""
 
 
+class GovernancePolicyConflictError(RuntimeError):
+    """Raised when a policy write was based on an obsolete revision."""
+
+
+class TokenBudgetExceededError(RuntimeError):
+    """Raised before a Cloud-proxied call would exceed a Host's token budget."""
+
+
 @dataclass(frozen=True)
 class UserSubmissionPolicy:
     user_id: str
@@ -30,6 +38,48 @@ class HostGovernancePolicy:
     updated_at: datetime
 
 
+@dataclass(frozen=True)
+class TokenReservation:
+    id: str
+    host_id: str
+    usage_day: str
+    reserved_tokens: int
+    task_id: str | None
+    attempt: int | None
+    created_at: datetime
+    expires_at: datetime
+
+
+@dataclass(frozen=True)
+class TokenUsageEvent:
+    id: str
+    host_id: str
+    usage_day: str
+    task_id: str | None
+    attempt: int | None
+    provider: str
+    model: str
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int
+    occurred_at: datetime
+
+
+@dataclass(frozen=True)
+class TokenUsageSummary:
+    host_id: str
+    usage_day: str
+    daily_token_budget: int | None
+    used_tokens: int
+    reserved_tokens: int
+
+    @property
+    def remaining_tokens(self) -> int | None:
+        if self.daily_token_budget is None:
+            return None
+        return max(0, self.daily_token_budget - self.used_tokens - self.reserved_tokens)
+
+
 def enforce_user_submission_policy(
     policy: UserSubmissionPolicy | None,
     *,