q792602257
1107ace89c
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.
71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
## 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.
|