agentic-mobile-control/openspec/specs/cloud-planner-proxy/spec.md

cloud-planner-proxy Specification

Purpose

Define the Cloud Control Plane's planner-decision proxy endpoint, which allows a Host Agent to delegate AI Planner LLM calls to the cloud using cloud-held provider credentials, removing the need for Host Agent-held provider API keys.

Requirements

Requirement: Cloud Control Plane exposes an authenticated planner-decision endpoint

The Cloud Control Plane SHALL expose an internal endpoint that accepts an AI Planner tool-calling decision request from an authenticated Host Agent, and SHALL require the same host-scoped bearer credential already used for heartbeat, claim, lease renewal, and result reporting -- no separate credential or enrollment step.

Scenario: Authenticated host requests a planner decision

• WHEN a Host Agent presents its existing valid host-scoped credentials with a planner-decision request
• THEN the Cloud Control Plane accepts and processes the request for that host

Scenario: Unauthenticated or foreign-host request is rejected

• WHEN a request omits valid host-scoped credentials, or presents credentials bound to a different host than the one referenced in the request
• THEN the Cloud Control Plane rejects the request without invoking any LLM provider

Requirement: Endpoint resolves exactly one tool-call decision using cloud-held provider configuration

The Cloud Control Plane SHALL use its own configured LLM provider, model, and credentials -- not any value supplied by the requesting Host Agent -- to resolve a planner-decision request to exactly one tool name and one arguments object, within the request's timeout. The endpoint SHALL resolve the active database-managed Provider profile for every request and use its provider, model, timeout, configured base URL, and encrypted cloud-held credential. It SHALL NOT read Cloud API planner Provider/model/timeout/API-key environment variables.

Scenario: Provider returns a usable decision

• WHEN the configured provider responds to a planner-decision request with a tool call
• THEN the Cloud Control Plane returns exactly one resolved tool name and arguments object to the requesting Host Agent

Scenario: Configured provider is unreachable or misconfigured

• WHEN the Cloud Control Plane's configured provider call fails (for example, invalid credentials, provider error, or timeout)
• THEN the endpoint returns a structured failure response rather than a fabricated decision, and does not crash the Cloud Control Plane process

Scenario: Database profile is the only planner configuration source

• WHEN the Cloud API process has legacy planner environment variables
• THEN subsequent planner-decision requests use only the active database profile and do not read a legacy Provider credential for that decision

Requirement: Cloud-proxy transport removes the need for Host Agent-held provider credentials

A Host Agent using the cloud-proxy transport for its AI Planner SHALL be able to execute AI-planned tasks without any locally configured LLM provider API key.

Scenario: Host configured for cloud-proxy transport has no local provider key

• WHEN a Host Agent is configured to use the cloud-proxy transport and has no ANTHROPIC_API_KEY/OPENAI_API_KEY set in its own environment
• THEN it can still obtain AI Planner decisions by calling the Cloud Control Plane's planner-decision endpoint

Requirement: Planner-decision requests are not durably persisted

The Cloud Control Plane SHALL process planner-decision requests, including any screenshot and prompt text they carry, without durably persisting that screenshot or prompt content; only request metadata (such as host identifier, resolved tool name, latency, and error classification) may be retained for observability.

Scenario: Request handling completes without storing prompt or screenshot content

• WHEN the Cloud Control Plane finishes handling a planner-decision request
• THEN the raw prompt text and screenshot bytes from that request are not present in any durable store or log the Cloud Control Plane retains

Requirement: Planner-proxy failures do not silently substitute a default action

The Cloud Control Plane SHALL report a failure to the requesting Host Agent when it cannot resolve a planner-decision request to a valid tool call, rather than returning a default, guessed, or previously cached decision.

Scenario: Endpoint cannot resolve a decision

• WHEN the configured provider does not return a usable tool call for a planner-decision request
• THEN the Cloud Control Plane's response indicates failure, and the requesting Host Agent treats the planner call for that turn as failed