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.
This commit is contained in:
@@ -91,15 +91,29 @@ reason about ("provider" would mean different things on each side).
|
||||
### D3: `CloudProxyToolCallingClient` lives in `host_agent`, not `runtime`
|
||||
`runtime/tool_calling_client.py`'s `ToolCallingClient` stays a plain
|
||||
`Protocol`; the new client is added in `apps/device-host-agent/host_agent/`
|
||||
(e.g. `host_agent/cloud_planner_client.py`) and satisfies that Protocol
|
||||
(`host_agent/cloud_planner_client.py`) and satisfies that Protocol
|
||||
structurally. This preserves the existing boundary enforced by
|
||||
`apps/device-host-agent/tests/test_execution.py::test_runtime_owned_packages_do_not_import_host_or_cloud_concerns`,
|
||||
which forbids `runtime` (and `core`/`device`/`driver`/`tools`) from
|
||||
importing `cloud` or `host_agent`. The new client wraps a new method on the
|
||||
existing `host_agent/client.py::HostAgentClient` (which already holds the
|
||||
authenticated `httpx` session and imports `cloud.internal_api.models`), so
|
||||
it reuses the same request/auth/retry plumbing as heartbeat/claim/renew/result
|
||||
instead of opening a second HTTP client type.
|
||||
importing `cloud` or `host_agent`.
|
||||
|
||||
Implementation note (revised during implementation from the original plan
|
||||
of wrapping `HostAgentClient`): `ToolCallingClient.decide()` is a
|
||||
**synchronous** Protocol method, and `AIPlanner.plan()` -> `TaskRunner`'s
|
||||
step loop runs inside a worker thread spawned via `asyncio.to_thread` (see
|
||||
`host_agent/lease.py`'s `ActiveAssignmentRunner`), off the main event loop.
|
||||
`HostAgentClient` holds an `httpx.AsyncClient` bound to that main loop, so
|
||||
calling it from the worker thread would require event-loop bridging
|
||||
(`asyncio.run_coroutine_threadsafe` or similar) for no benefit over a
|
||||
simpler alternative. Instead, `CloudProxyToolCallingClient` holds its own
|
||||
synchronous `httpx.Client`, mirroring the existing
|
||||
`host_agent/client.py::HostAgentEnrollmentClient` pattern (same
|
||||
`Authorization: Bearer` header construction, same base URL from
|
||||
`HostAgentConfig`), rather than reusing `HostAgentClient`'s async session.
|
||||
It still imports request/response models directly from
|
||||
`cloud.internal_api.models` -- no duplicated schemas -- so the "no new
|
||||
wire-format definitions" intent of D1 is preserved even though the HTTP
|
||||
transport itself isn't literally shared with `HostAgentClient`.
|
||||
|
||||
### D4: Reuse the existing host-scoped bearer credential; no new auth scope
|
||||
The new endpoint sits on the same internal router and auth dependency as
|
||||
@@ -157,12 +171,16 @@ proposal does not change that risk profile, only where the call happens.
|
||||
Control Plane** -> Mitigation: D6 (no durable persistence); still an
|
||||
expansion of the data path operators should account for versus
|
||||
direct-to-provider, which never touches the cloud.
|
||||
- **[Risk] Cloud API gains a new dependency on `anthropic`/`openai` SDKs
|
||||
and becomes a second place holding provider credentials** -> Mitigation:
|
||||
reusing `runtime.tool_calling_client` (D1) keeps this to configuration
|
||||
and routing, not new provider-integration code; credential handling
|
||||
follows the same "environment or secret manager" pattern already
|
||||
documented for the Host Agent in `docs/CLOUD_DEPLOYMENT.md`.
|
||||
- **[Risk] Cloud API becomes a second place holding provider credentials**
|
||||
-> Mitigation: reusing `runtime.tool_calling_client` (D1) keeps this to
|
||||
configuration and routing, not new provider-integration code; credential
|
||||
handling follows the same "environment or secret manager" pattern already
|
||||
documented for the Host Agent in `docs/CLOUD_DEPLOYMENT.md`. Note: this is
|
||||
not a *new* package-dependency footprint -- `device-cloud-platform`
|
||||
already depends unconditionally on `device-agent-runtime`, which declares
|
||||
`anthropic`/`openai`, so both SDKs are already installed wherever the
|
||||
Cloud API runs today (verified with `uv run`); only the credentials
|
||||
themselves are new.
|
||||
- **[Risk] Any authenticated host can drive cloud-held LLM spend** (D4) ->
|
||||
Mitigation: none in this proposal beyond existing per-host authentication;
|
||||
flagged as an Open Question rather than silently accepted, since it's a
|
||||
|
||||
Reference in New Issue
Block a user