Implement cloud-planner-proxy: AI planner routes through Cloud API

Implements all 19 tasks of the cloud-planner-proxy OpenSpec change:

- Cloud API: cloud.planner_config (CloudPlannerConfig, load/build helpers)
  reusing runtime.tool_calling_client provider clients (no new dependency
  needed -- device-cloud-platform already depends on device-agent-runtime).
- Cloud API: new host-scoped POST /internal/v1/hosts/{host_id}/planner/decide
  internal endpoint, reusing existing bearer auth; logs only metadata
  (host id, tool name, latency, error class), never prompt/screenshot
  content.
- Host Agent: new AI_PLANNER_TRANSPORT config (direct default | cloud) and
  host_agent/cloud_planner_client.py::CloudProxyToolCallingClient, a
  synchronous ToolCallingClient implementation (structural, not importing
  runtime) that calls the new endpoint via its own httpx.Client -- avoids
  bridging the async HostAgentClient across the worker-thread boundary
  that AIPlanner.plan() runs in (asyncio.to_thread in lease.py).
- Host Agent wiring: create_execution_factories()/_host_agent_planner()
  select the cloud-proxy client only when AI_PLANNER_TRANSPORT=cloud;
  direct/unset transport is unchanged (still the default).
- Tests: 22 new tests across Cloud API config, the new endpoint, the new
  client, and transport-selection wiring; full non-integration suite
  (492 tests) passes with no regressions.
- Docs: docs/CLOUD_DEPLOYMENT.md documents the cloud transport, its
  trade-offs, and the credential split between Host Agent and Cloud API.

proposal.md/design.md were corrected during implementation to reflect two
findings: no new anthropic/openai dependency is actually needed, and
CloudProxyToolCallingClient uses its own sync httpx.Client rather than a
new HostAgentClient method, per the thread-boundary reasoning above.

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

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import asyncio
+import base64
+import logging
 from collections.abc import Awaitable, Callable
 from datetime import timedelta
 from time import monotonic
@@ -27,19 +29,27 @@ from cloud.internal_api.models import (
     HostEnrollmentResponse,
     LeaseRenewalRequest,
     LeaseRenewalResponse,
+    PlannerDecisionError,
+    PlannerDecisionRequest,
+    PlannerDecisionResponse,
     StaleLeaseConflict,
     TerminalResultRequest,
     TerminalResultResponse,
 )
+from cloud.planner_config import build_cloud_planner_client, load_cloud_planner_config
 from cloud.repository import (
     DeviceEnrollmentConflictError,
     HostEnrollmentConflictError,
 )
 from core.models import Device, utc_now
+from runtime.tool_calling_client import ToolCallingClient, ToolCallUnavailable
+from runtime.tool_specs import ToolSpec
 
 if TYPE_CHECKING:
     from cloud.pool import DevicePool
 
+logger = logging.getLogger(__name__)
+
 
 def create_internal_router(
     *,
@@ -49,12 +59,15 @@ def create_internal_router(
     claim_poll_interval_seconds: float = 0.1,
     lease_duration_seconds: float = 60.0,
     sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    planner_client_factory: Callable[[], ToolCallingClient] | None = None,
 ) -> APIRouter:
     if claim_poll_interval_seconds <= 0:
         raise ValueError("claim_poll_interval_seconds must be greater than zero")
     if lease_duration_seconds <= 0:
         raise ValueError("lease_duration_seconds must be greater than zero")
     router = APIRouter(prefix=version_prefix, tags=["host-agent"])
+    build_planner_client = planner_client_factory or _default_planner_client_factory
+
     def authorize_host(request: Request, host_id: str) -> None:
         principal = auth_provider.authenticate(request)
         if principal is None:
@@ -269,9 +282,87 @@ def create_internal_router(
             return _stale_lease_conflict("assignment lease is stale or superseded")
         return TerminalResultResponse(status=result_status)
 
+    @router.post(
+        "/hosts/{host_id}/planner/decide",
+        response_model=PlannerDecisionResponse,
+        responses={
+            status.HTTP_502_BAD_GATEWAY: {"model": PlannerDecisionError},
+        },
+    )
+    def decide_planner_call(
+        host_id: str,
+        payload: PlannerDecisionRequest,
+        request: Request,
+    ):
+        authorize_host(request, host_id)
+        if payload.host_id != host_id:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+                detail="planner-decision host_id must match the request path",
+            )
+
+        screenshot: bytes | None = None
+        if payload.screenshot_base64 is not None:
+            try:
+                screenshot = base64.b64decode(payload.screenshot_base64)
+            except ValueError, TypeError:
+                raise HTTPException(
+                    status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+                    detail="screenshot_base64 is not valid base64",
+                ) from None
+
+        tools = [
+            ToolSpec(
+                name=tool.name,
+                description=tool.description,
+                parameters=tool.parameters,
+            )
+            for tool in payload.tools
+        ]
+
+        started_at = monotonic()
+        client = build_planner_client()
+        try:
+            decision = client.decide(
+                system_prompt=payload.system_prompt,
+                user_prompt=payload.user_prompt,
+                screenshot=screenshot,
+                tools=tools,
+                timeout=payload.timeout_seconds,
+            )
+        except ToolCallUnavailable as exc:
+            logger.info(
+                "planner-decision request failed",
+                extra={
+                    "host_id": host_id,
+                    "latency_seconds": monotonic() - started_at,
+                    "error_class": type(exc).__name__,
+                },
+            )
+            return JSONResponse(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                content=PlannerDecisionError(detail=str(exc)).model_dump(),
+            )
+        logger.info(
+            "planner-decision request resolved",
+            extra={
+                "host_id": host_id,
+                "tool_name": decision.tool_name,
+                "latency_seconds": monotonic() - started_at,
+            },
+        )
+        return PlannerDecisionResponse(
+            tool_name=decision.tool_name,
+            arguments=dict(decision.arguments),
+        )
+
     return router
 
 
+def _default_planner_client_factory() -> ToolCallingClient:
+    return build_cloud_planner_client(load_cloud_planner_config())
+
+
 def _validate_assignment_identity(
     *,
     host_id: str,

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

@@ -96,3 +96,28 @@ class TerminalResultResponse(BaseModel):
 class StaleLeaseConflict(BaseModel):
     code: Literal["stale_lease"] = "stale_lease"
     detail: str
+
+
+class PlannerToolSpecModel(BaseModel):
+    name: str = Field(min_length=1)
+    description: str = ""
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlannerDecisionRequest(BaseModel):
+    host_id: str = Field(min_length=1)
+    system_prompt: str
+    user_prompt: str
+    screenshot_base64: str | None = None
+    tools: list[PlannerToolSpecModel] = Field(default_factory=list)
+    timeout_seconds: float = Field(default=30.0, gt=0, le=120)
+
+
+class PlannerDecisionResponse(BaseModel):
+    tool_name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlannerDecisionError(BaseModel):
+    code: Literal["planner_unavailable"] = "planner_unavailable"
+    detail: str