agentic-mobile-control/openspec/changes/cloud-planner-proxy/proposal.md at 1107ace89cbcc873932c473a4d61f96a0aa44a28

q792602257/agentic-mobile-control

Fork 0

Files

T

q792602257 1107ace89c

Tests / Test passed: 626

Details

Default-enable AI Planner in Host Agent; propose cloud-planner-proxy

- 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.

2026-07-13 20:50:35 +08:00

3.8 KiB

Raw Blame History

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.

3.8 KiB Raw Blame History

Why