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/tests/test_cloud_planner_client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from host_agent.cloud_planner_client import CloudProxyToolCallingClient
+from host_agent.config import HostAgentConfig
+from runtime.tool_calling_client import ToolCallDecision, ToolCallUnavailable
+from runtime.tool_specs import ToolSpec
+
+_CONFIG = HostAgentConfig(
+    control_plane_url="https://control-plane.example",
+    host_id="host-a",
+    token="token-a",
+)
+
+_TOOLS = [ToolSpec(name="tap", description="tap an element", parameters={})]
+
+
+def _client(handler) -> CloudProxyToolCallingClient:
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.Client(base_url=_CONFIG.control_plane_url, transport=transport)
+    return CloudProxyToolCallingClient(_CONFIG, http_client=http_client)
+
+
+def test_decide_returns_tool_call_decision_on_success() -> None:
+    seen_requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_requests.append(request)
+        return httpx.Response(
+            200,
+            json={"tool_name": "tap", "arguments": {"x": 1, "y": 2}},
+        )
+
+    client = _client(handler)
+
+    decision = client.decide(
+        system_prompt="you are a planner",
+        user_prompt="tap login",
+        screenshot=None,
+        tools=_TOOLS,
+        timeout=30.0,
+    )
+
+    assert decision == ToolCallDecision(tool_name="tap", arguments={"x": 1, "y": 2})
+    assert len(seen_requests) == 1
+    request = seen_requests[0]
+    assert request.url.path == "/internal/v1/hosts/host-a/planner/decide"
+    assert request.headers["Authorization"] == "Bearer token-a"
+    body = json.loads(request.content)
+    assert body["host_id"] == "host-a"
+    assert body["system_prompt"] == "you are a planner"
+    assert body["screenshot_base64"] is None
+    assert body["timeout_seconds"] == 30.0
+
+
+def test_decide_base64_encodes_screenshot() -> None:
+    seen_requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_requests.append(request)
+        return httpx.Response(200, json={"tool_name": "tap", "arguments": {}})
+
+    client = _client(handler)
+
+    client.decide(
+        system_prompt="sp",
+        user_prompt="up",
+        screenshot=b"hello",
+        tools=_TOOLS,
+        timeout=10.0,
+    )
+
+    body = json.loads(seen_requests[0].content)
+    assert body["screenshot_base64"] == "aGVsbG8="
+
+
+def test_decide_raises_tool_call_unavailable_on_network_error() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("connection refused", request=request)
+
+    client = _client(handler)
+
+    with pytest.raises(ToolCallUnavailable):
+        client.decide(
+            system_prompt="sp",
+            user_prompt="up",
+            screenshot=None,
+            tools=_TOOLS,
+            timeout=5.0,
+        )
+
+
+def test_decide_raises_tool_call_unavailable_on_structured_error_response() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            502,
+            json={"code": "planner_unavailable", "detail": "provider timed out"},
+        )
+
+    client = _client(handler)
+
+    with pytest.raises(ToolCallUnavailable, match="provider timed out"):
+        client.decide(
+            system_prompt="sp",
+            user_prompt="up",
+            screenshot=None,
+            tools=_TOOLS,
+            timeout=5.0,
+        )
+
+
+def test_decide_raises_tool_call_unavailable_on_unstructured_error_response() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, text="internal server error")
+
+    client = _client(handler)
+
+    with pytest.raises(ToolCallUnavailable):
+        client.decide(
+            system_prompt="sp",
+            user_prompt="up",
+            screenshot=None,
+            tools=_TOOLS,
+            timeout=5.0,
+        )
+
+
+def test_close_closes_an_internally_constructed_http_client() -> None:
+    client = CloudProxyToolCallingClient(_CONFIG)
+    client.close()
+
+    assert client._client.is_closed
+
+
+def test_close_leaves_an_externally_supplied_http_client_open() -> None:
+    """Only a client built internally (no ``http_client`` override) is closed
+    by ``close()``; a caller-supplied ``http_client`` is left open for the
+    caller to manage."""
+    transport = httpx.MockTransport(lambda request: httpx.Response(200, json={}))
+    external_http_client = httpx.Client(
+        base_url=_CONFIG.control_plane_url, transport=transport
+    )
+
+    client = CloudProxyToolCallingClient(_CONFIG, http_client=external_http_client)
+    client.close()
+
+    assert not external_http_client.is_closed
+    external_http_client.close()