feat(cloud): attribute planner token usage

packages/cloud-platform/cloud/internal_api/api.py

@@ -373,6 +373,7 @@ def create_internal_router(
                 status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 detail="planner-decision host_id must match the request path",
             )
+        _validate_planner_context(pool, host_id=host_id, payload=payload)
 
         screenshot: bytes | None = None
         if payload.screenshot_base64 is not None:
@@ -401,8 +402,8 @@ def create_internal_router(
                 host_id=host_id,
                 usage_day=now.date().isoformat(),
                 reserved_tokens=planner_token_reservation_ceiling,
-                task_id=None,
-                attempt=None,
+                task_id=payload.task_id,
+                attempt=payload.attempt,
                 created_at=now,
                 expires_at=now + timedelta(seconds=planner_token_reservation_ttl_seconds),
             )
@@ -485,6 +486,28 @@ def _validate_assignment_identity(
         )
 
 
+def _validate_planner_context(pool, *, host_id: str, payload: PlannerDecisionRequest) -> None:
+    context_values = (payload.task_id, payload.attempt, payload.lease_id)
+    if not any(value is not None for value in context_values):
+        return
+    if any(value is None for value in context_values):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail="planner context requires task_id, attempt, and lease_id together",
+        )
+    attempts = pool.store.list_task_attempts(payload.task_id or "")
+    if not any(
+        attempt.attempt == payload.attempt
+        and attempt.host_id == host_id
+        and attempt.lease_id == payload.lease_id
+        for attempt in attempts
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail="planner context does not match a Host assignment",
+        )
+
+
 def _stale_lease_conflict(detail: str) -> JSONResponse:
     return JSONResponse(
         status_code=status.HTTP_409_CONFLICT,

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

@@ -131,6 +131,9 @@ class PlannerDecisionRequest(BaseModel):
     screenshot_base64: str | None = None
     tools: list[PlannerToolSpecModel] = Field(default_factory=list)
     timeout_seconds: float = Field(default=30.0, gt=0, le=120)
+    task_id: str | None = Field(default=None, min_length=1)
+    attempt: int | None = Field(default=None, ge=1)
+    lease_id: str | None = Field(default=None, min_length=1)
 
 
 class PlannerDecisionResponse(BaseModel):

packages/cloud-platform/cloud/repository.py

@@ -336,6 +336,10 @@ class CloudRepository(Protocol):
         self, *, host_id: str, usage_day: str, now: datetime,
     ) -> TokenUsageSummary: ...
 
+    def list_host_token_usage_events(
+        self, *, host_id: str, limit: int, offset: int,
+    ) -> list[TokenUsageEvent]: ...
+
     def list_reserved_device_ids(self, *, now: datetime) -> set[str]: ...
 
     def assign_task(

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

packages/cloud-platform/cloud/sql_repository.py

@@ -1046,6 +1046,19 @@ class SQLAlchemyCloudRepository:
             used_tokens=int(used or 0), reserved_tokens=int(reserved or 0),
         )
 
+    def list_host_token_usage_events(
+        self, *, host_id: str, limit: int, offset: int,
+    ) -> list[Any]:
+        with self._sessions() as session:
+            rows = session.scalars(
+                select(TokenUsageEventRow)
+                .where(TokenUsageEventRow.host_id == host_id)
+                .order_by(TokenUsageEventRow.occurred_at.desc(), TokenUsageEventRow.id.desc())
+                .limit(limit)
+                .offset(offset)
+            ).all()
+        return [_token_usage_event_from_row(row) for row in rows]
+
     def list_reserved_device_ids(self, *, now: datetime) -> set[str]:
         with self._sessions() as session:
             device_ids = session.scalars(