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.

apps/device-host-agent/host_agent/app.py

@@ -196,7 +196,12 @@ def create_application(
             else None
         ),
     )
-    executor = AssignmentExecutor(create_execution_factories(resolved_manager))
+    executor = AssignmentExecutor(
+        create_execution_factories(
+            resolved_manager,
+            host_agent_config=resolved_config,
+        )
+    )
     active_runner = ActiveAssignmentRunner(client, executor)
     processor = AssignmentProcessor(
         client,

apps/device-host-agent/host_agent/cloud_planner_client.py

@@ -0,0 +1,109 @@
+"""``ToolCallingClient`` implementation that proxies AI Planner decisions
+through the Cloud Control Plane instead of calling an LLM provider directly.
+
+Lives in ``host_agent``, not ``runtime`` (design decision D3): the shared
+Runtime package's boundary test
+(``apps/device-host-agent/tests/test_execution.py::test_runtime_owned_packages_do_not_import_host_or_cloud_concerns``)
+forbids ``runtime`` from importing ``cloud`` or ``host_agent``, so this class
+satisfies ``runtime.tool_calling_client.ToolCallingClient`` structurally
+from outside that package instead of living inside it.
+
+Uses its own synchronous ``httpx.Client`` (mirroring
+``HostAgentEnrollmentClient``'s pattern) rather than wrapping the async
+``HostAgentClient``: ``ToolCallingClient.decide()`` is a synchronous Protocol
+method invoked from a worker thread via ``asyncio.to_thread`` (see
+``host_agent/lease.py``), off the main event loop, so reusing an
+``httpx.AsyncClient`` bound to that loop would require event-loop bridging
+for no real benefit over a plain synchronous client with the same
+host-scoped bearer auth.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+
+from cloud.internal_api.models import PlannerDecisionError, PlannerDecisionResponse
+from host_agent.config import HostAgentConfig
+from runtime.tool_calling_client import ToolCallDecision, ToolCallUnavailable
+from runtime.tool_specs import ToolSpec
+
+
+class CloudProxyToolCallingClient:
+    def __init__(
+        self,
+        config: HostAgentConfig,
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.config = config
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(base_url=config.control_plane_url)
+
+    def decide(
+        self,
+        *,
+        system_prompt: str,
+        user_prompt: str,
+        screenshot: bytes | None,
+        tools: list[ToolSpec],
+        timeout: float,
+    ) -> ToolCallDecision:
+        payload: dict[str, Any] = {
+            "host_id": self.config.host_id,
+            "system_prompt": system_prompt,
+            "user_prompt": user_prompt,
+            "screenshot_base64": (
+                base64.b64encode(screenshot).decode("ascii")
+                if screenshot is not None
+                else None
+            ),
+            "tools": [
+                {
+                    "name": spec.name,
+                    "description": spec.description,
+                    "parameters": spec.parameters,
+                }
+                for spec in tools
+            ],
+            "timeout_seconds": timeout,
+        }
+        try:
+            response = self._client.post(
+                f"/internal/v1/hosts/{self.config.host_id}/planner/decide",
+                json=payload,
+                headers={"Authorization": f"Bearer {self.config.token}"},
+                timeout=timeout + 5,
+            )
+        except httpx.HTTPError as exc:
+            raise ToolCallUnavailable(str(exc)) from exc
+
+        if response.is_success:
+            decoded = PlannerDecisionResponse.model_validate(response.json())
+            return ToolCallDecision(
+                tool_name=decoded.tool_name,
+                arguments=dict(decoded.arguments),
+            )
+        raise ToolCallUnavailable(_error_detail(response))
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+def _error_detail(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        return f"planner-decision request failed with status {response.status_code}"
+    try:
+        error = PlannerDecisionError.model_validate(payload)
+    except Exception:
+        detail = payload.get("detail") if isinstance(payload, dict) else None
+        return (
+            detail
+            or f"planner-decision request failed with status {response.status_code}"
+        )
+    return error.detail

apps/device-host-agent/host_agent/config.py

@@ -12,6 +12,7 @@ class HostAgentConfigurationError(ValueError):
 
 
 _LOOPBACK_BIND_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+_AI_PLANNER_TRANSPORTS = frozenset({"direct", "cloud"})
 
 
 @dataclass(frozen=True)
@@ -34,6 +35,7 @@ class HostAgentConfig:
     console_allow_non_loopback: bool = False
     console_session_ttl_seconds: float = 43200.0
     console_history_limit: int = 200
+    ai_planner_transport: str = "direct"
 
 
 def load_host_agent_config(
@@ -112,6 +114,9 @@ def load_host_agent_config(
             "HOST_AGENT_CONSOLE_HISTORY_LIMIT",
             200,
         ),
+        ai_planner_transport=_parse_ai_planner_transport(
+            values.get("AI_PLANNER_TRANSPORT")
+        ),
     )
     if config.max_retry_backoff_seconds < config.retry_backoff_seconds:
         raise HostAgentConfigurationError(
@@ -129,6 +134,18 @@ def load_host_agent_config(
     return config
 
 
+def _parse_ai_planner_transport(value: str | None) -> str:
+    if value is None:
+        return "direct"
+    transport = value.strip().lower()
+    if transport not in _AI_PLANNER_TRANSPORTS:
+        raise HostAgentConfigurationError(
+            "AI_PLANNER_TRANSPORT must be one of "
+            f"{', '.join(sorted(_AI_PLANNER_TRANSPORTS))}"
+        )
+    return transport
+
+
 def _positive_float(
     values: Mapping[str, str],
     name: str,

apps/device-host-agent/host_agent/execution.py

@@ -5,7 +5,11 @@ from collections.abc import Callable
 from dataclasses import dataclass, replace
 
 from device.manager import DeviceManager
+from host_agent.cloud_planner_client import CloudProxyToolCallingClient
+from host_agent.config import HostAgentConfig, load_host_agent_config
+from runtime.ai_planner import AIPlanner
 from runtime.executor import Executor, default_tool_registry
+from runtime.planner import Planner
 from runtime.planner_config import PlannerConfig, load_config as load_planner_config
 from runtime.task import TaskRunner
 from storage.task_metadata import TaskMetadataStore
@@ -27,14 +31,17 @@ def create_execution_factories(
     workflow_store: WorkflowStore | None = None,
     metadata_store: TaskMetadataStore | None = None,
     timeline: Timeline | None = None,
+    host_agent_config: HostAgentConfig | None = None,
 ) -> ExecutionFactories:
     shared_workflow_store = workflow_store or WorkflowStore()
+    resolved_host_agent_config = host_agent_config
 
     def create_task_runner() -> TaskRunner:
         return TaskRunner(
             executor=Executor(tools=default_tool_registry(manager=manager)),
             metadata_store=metadata_store,
             timeline=timeline,
+            planner=_host_agent_planner(resolved_host_agent_config),
             planner_config=_host_agent_planner_config(),
         )
 
@@ -64,3 +71,28 @@ def _host_agent_planner_config() -> PlannerConfig:
     if os.environ.get("AI_PLANNER_ENABLED") is None:
         config = replace(config, enabled=True)
     return config
+
+
+def _host_agent_planner(
+    host_agent_config: HostAgentConfig | None,
+) -> Planner | None:
+    """Build the `AIPlanner` explicitly when the cloud-proxy transport is
+    selected, so its `ToolCallingClient` is a `CloudProxyToolCallingClient`
+    instead of a local Anthropic/OpenAI SDK client.
+
+    Returns `None` (letting `TaskRunner` fall back to its own
+    `_default_planner()`) for the `direct` transport, which preserves the
+    existing default-enabled/direct-to-provider behavior unchanged.
+    """
+    planner_config = _host_agent_planner_config()
+    if not planner_config.enabled:
+        return None
+
+    resolved_config = host_agent_config or load_host_agent_config()
+    if resolved_config.ai_planner_transport != "cloud":
+        return None
+
+    return AIPlanner(
+        client=CloudProxyToolCallingClient(resolved_config),
+        config=planner_config,
+    )