q792602257
a68f609453
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.
110 lines
3.9 KiB
Python
110 lines
3.9 KiB
Python
"""``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
|