feat(cloud): attribute planner token usage

packages/cloud-platform/cloud/sdk/client.py

@@ -240,6 +240,18 @@ class CloudClient:
             "PUT", f"/hosts/{host_id}/governance-policy", json=policy
         ).json()
 
+    def get_host_token_usage(self, host_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/hosts/{host_id}/token-usage").json()
+
+    def list_host_token_usage_events(
+        self, host_id: str, *, limit: int = 50, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        return self._request(
+            "GET",
+            f"/hosts/{host_id}/token-usage-events",
+            params={"limit": limit, "offset": offset},
+        ).json()
+
     # ------------------------------------------------------------------ helpers
 
     def _url(self, path: str) -> str:

packages/cloud-platform/cloud/sdk/governance_api.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from uuid import uuid4
 
-from fastapi import APIRouter, HTTPException, Request, status
+from fastapi import APIRouter, HTTPException, Query, Request, status
 
 from cloud.auth import AuthProvider, GOVERNANCE_ADMIN_SCOPE, GOVERNANCE_READ_SCOPE
 from cloud.governance import GovernancePolicyConflictError
@@ -11,6 +11,7 @@ from cloud.sdk.models import (
     HostGovernancePolicyRequest,
     HostGovernancePolicyResponse,
     HostTokenUsageSummaryResponse,
+    TokenUsageEventResponse,
     UserSubmissionPolicyRequest,
     UserSubmissionPolicyResponse,
 )
@@ -137,6 +138,36 @@ def create_governance_router(*, repository, auth_provider: AuthProvider) -> APIR
             remaining_tokens=summary.remaining_tokens,
         )
 
+    @router.get(
+        "/hosts/{host_id}/token-usage-events",
+        response_model=list[TokenUsageEventResponse],
+    )
+    def list_host_token_usage_events(
+        host_id: str,
+        request: Request,
+        limit: int = Query(default=50, ge=1, le=100),
+        offset: int = Query(default=0, ge=0),
+    ) -> list[TokenUsageEventResponse]:
+        authorize(request, GOVERNANCE_READ_SCOPE)
+        return [
+            TokenUsageEventResponse(
+                id=event.id,
+                host_id=event.host_id,
+                usage_day=event.usage_day,
+                task_id=event.task_id,
+                attempt=event.attempt,
+                provider=event.provider,
+                model=event.model,
+                input_tokens=event.input_tokens,
+                output_tokens=event.output_tokens,
+                total_tokens=event.total_tokens,
+                occurred_at=event.occurred_at,
+            )
+            for event in repository.list_host_token_usage_events(
+                host_id=host_id, limit=limit, offset=offset
+            )
+        ]
+
     @router.put(
         "/hosts/{host_id}/governance-policy",
         response_model=HostGovernancePolicyResponse,

packages/cloud-platform/cloud/sdk/models.py

@@ -197,3 +197,17 @@ class HostTokenUsageSummaryResponse(BaseModel):
     used_tokens: int
     reserved_tokens: int
     remaining_tokens: int | None = None
+
+
+class TokenUsageEventResponse(BaseModel):
+    id: str
+    host_id: str
+    usage_day: str
+    task_id: str | None = None
+    attempt: int | None = None
+    provider: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int
+    occurred_at: datetime