agentic-mobile-control/openspec/changes/archive/2026-07-14-cloud-planner-proxy/proposal.md

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 transport setting (cloud-proxy vs. direct-to-provider) and a new ToolCallingClient implementation that calls the cloud endpoint instead of constructing a local Anthropic/OpenAI SDK client. Cloud-proxy is the default; the existing direct-to-provider transport remains fully supported as an explicit opt-out for hosts with local provider keys.
• 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. No new package dependency: device-cloud-platform already depends unconditionally on device-agent-runtime (which declares anthropic/ openai), so both SDKs are already present wherever the Cloud API runs -- confirmed by uv run python -c "import anthropic, openai" succeeding in the workspace venv without any pyproject change.
• apps/device-host-agent: a new ToolCallingClient implementation (host_agent/cloud_planner_client.py::CloudProxyToolCallingClient, constructed in the host_agent package, not runtime, to preserve the existing hexagonal boundary that forbids runtime from importing cloud or host_agent) with its own synchronous httpx.Client (matching HostAgentEnrollmentClient's pattern, since ToolCallingClient.decide() runs synchronously off the main event loop), and a new transport configuration setting (AI_PLANNER_TRANSPORT).
• 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.