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

packages/cloud-platform/cloud/planner_config.py

@@ -0,0 +1,86 @@
+"""Cloud Control Plane's own AI Planner provider configuration.
+
+Analogous to ``runtime/planner_config.py``, but loaded from the Cloud API's
+own process environment rather than a Host Agent's. There is no ``enabled``
+flag here: the planner-decision endpoint always exists once the Cloud API is
+running, and simply fails a given request if the configured provider call
+fails (see ``cloud.internal_api.api``). Provider API keys
+(``ANTHROPIC_API_KEY``/``OPENAI_API_KEY``) are not modeled as fields here --
+like the Host Agent's direct-transport path, they are read implicitly by the
+``anthropic``/``openai`` SDK clients from the process environment.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from runtime.tool_calling_client import (
+    AnthropicToolCallingClient,
+    OpenAIToolCallingClient,
+    ToolCallingClient,
+)
+
+DEFAULT_PROVIDER = "anthropic"
+DEFAULT_MODEL_BY_PROVIDER = {
+    "anthropic": "claude-sonnet-5",
+    "openai": "gpt-5.6",
+}
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+PROVIDER_ENV = "AI_PLANNER_PROVIDER"
+MODEL_ENV = "AI_PLANNER_MODEL"
+TIMEOUT_ENV = "AI_PLANNER_TIMEOUT_SECONDS"
+
+SUPPORTED_PROVIDERS = frozenset(DEFAULT_MODEL_BY_PROVIDER)
+
+
+@dataclass(frozen=True)
+class CloudPlannerConfig:
+    provider: str = DEFAULT_PROVIDER
+    model: str = ""
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+
+    def resolved_model(self) -> str:
+        return self.model or DEFAULT_MODEL_BY_PROVIDER[self.provider]
+
+
+def load_cloud_planner_config(
+    env: Mapping[str, str] | None = None,
+) -> CloudPlannerConfig:
+    values = env or os.environ
+    return CloudPlannerConfig(
+        provider=_parse_provider(values.get(PROVIDER_ENV)),
+        model=values.get(MODEL_ENV) or "",
+        timeout=_parse_timeout(values.get(TIMEOUT_ENV)),
+    )
+
+
+def build_cloud_planner_client(config: CloudPlannerConfig) -> ToolCallingClient:
+    """Construct the same provider client the Host Agent's direct transport uses.
+
+    Reuses ``runtime.tool_calling_client``'s Anthropic/OpenAI wire-format
+    translation (see design decision D1) instead of a second implementation.
+    """
+    model = config.resolved_model()
+    if config.provider == "openai":
+        return OpenAIToolCallingClient(model=model)
+    return AnthropicToolCallingClient(model=model)
+
+
+def _parse_provider(value: str | None) -> str:
+    if value is None:
+        return DEFAULT_PROVIDER
+    provider = value.strip().lower()
+    return provider if provider in SUPPORTED_PROVIDERS else DEFAULT_PROVIDER
+
+
+def _parse_timeout(value: str | None) -> float:
+    if value is None:
+        return DEFAULT_TIMEOUT_SECONDS
+    try:
+        timeout = float(value)
+    except ValueError:
+        return DEFAULT_TIMEOUT_SECONDS
+    return timeout if timeout > 0 else DEFAULT_TIMEOUT_SECONDS