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.
2026-07-13 21:27:48 +08:00
parent 1107ace89c
commit a68f609453
15 changed files with 1009 additions and 60 deletions
@@ -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