Default-enable AI Planner in Host Agent; propose cloud-planner-proxy
Tests / Test passed: 626

- Host Agent now defaults AI_PLANNER_ENABLED=true (opt-out via env),
  scoped to apps/device-host-agent/host_agent/execution.py only; the
  shared runtime.planner_config default (disabled) is unchanged.
- Add openspec proposal for cloud-planner-proxy: centralize LLM
  provider config/credentials on the Cloud Control Plane and let the
  Host Agent proxy AI Planner decisions through it instead of holding
  provider API keys locally. Proposal only, no implementation yet.
This commit is contained in:
2026-07-13 20:50:35 +08:00
parent 78ce788e2f
commit 1107ace89c
9 changed files with 537 additions and 5 deletions
@@ -0,0 +1,70 @@
## Why
Today every Host Agent must hold its own LLM provider credentials
(`ANTHROPIC_API_KEY`/`OPENAI_API_KEY`) and provider/model configuration
locally, because `runtime/ai_planner.py`'s `AIPlanner` builds an
Anthropic/OpenAI SDK client directly inside the Host Agent process
(`runtime/tool_calling_client.py`). With the Host Agent now defaulting AI
planning to on, this means every edge deployment must independently
provision, rotate, and secure a provider secret. Centralizing provider
configuration and credentials in the Cloud Control Plane -- which already
authenticates every Host Agent for heartbeat/claim/lease/result traffic --
removes per-edge secret sprawl and gives operators one place to change
provider/model or rotate a key without touching any Host.
## What Changes
- Add a new Cloud Control Plane internal endpoint that accepts an AI
Planner tool-calling decision request (system prompt, user prompt,
optional screenshot, tool specs, timeout) from an authenticated Host
Agent, calls the configured LLM provider using cloud-held credentials,
and returns the resulting single tool-call decision.
- Cloud API owns `AI_PLANNER_PROVIDER`/`AI_PLANNER_MODEL`/provider API keys
as its own configuration; these are no longer required on the Host Agent
when the new proxy transport is used.
- Host Agent gains a new opt-in transport setting (proxy vs. direct-to-provider)
and a new `ToolCallingClient` implementation that calls the cloud endpoint
instead of constructing a local Anthropic/OpenAI SDK client. The existing
direct-to-provider transport remains fully supported and is the default,
so hosts that already run with a local provider key keep working
unchanged.
- Reuse the existing Host-scoped bearer credential (already used for
heartbeat/claim/renew/result) for the new endpoint; no new auth scope.
- Cloud API does not durably persist screenshot bytes or full prompt text
from proxy requests beyond the lifetime of handling the request.
## Capabilities
### New Capabilities
- `cloud-planner-proxy`: Cloud Control Plane internal endpoint and
configuration that proxies AI Planner LLM tool-calling decisions on
behalf of authenticated Host Agents, holding provider selection and
credentials centrally instead of on each edge host.
### Modified Capabilities
- `agent-runtime` (capability defined by the not-yet-archived
`ai-planner-runtime` change; this delta is written against that pending
spec, matching the precedent set by `edge-host-self-enrollment` against
the pending `edge-host-enrollment` spec): the "Pluggable dual-provider
tool-calling abstraction" requirement is extended so the tool-calling
client is selectable by transport (direct-to-provider vs. cloud-proxy) as
well as by provider identity, and provider credentials become optional on
the Host Agent when the cloud-proxy transport is selected.
## Impact
- `packages/cloud-platform/cloud` / `apps/cloud-api`: new internal API
route + request/response models, new provider/credential configuration,
and a new direct dependency on the `anthropic`/`openai` SDKs (currently
only the root Runtime package depends on them -- this is new dependency
and attack surface for the Cloud API).
- `apps/device-host-agent`: new `HostAgentClient` method for the
planner-decide call, a new `ToolCallingClient` implementation
(constructed in the `host_agent` package, not `runtime`, to preserve the
existing hexagonal boundary that forbids `runtime` from importing `cloud`
or `host_agent`), and a new transport configuration setting.
- `runtime/tool_calling_client.py`: no changes to the `ToolCallingClient`
Protocol itself; the new implementation satisfies it structurally from
outside the `runtime` package.
- Docs: `docs/CLOUD_DEPLOYMENT.md` Runtime AI Planner section gains the
proxy-transport configuration path and its trade-offs.