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,43 @@
## MODIFIED Requirements
### Requirement: Pluggable dual-provider tool-calling abstraction
The system SHALL support at least two interchangeable LLM providers
(Anthropic native tool use and OpenAI function calling) for the AI
Planner's decision calls, selectable via configuration, with both providers
constrained to return exactly one tool call per request. Independently of
provider selection, the system SHALL support at least two transports for
making that decision call -- direct-to-provider (the tool-calling client
calls the provider's SDK itself, using locally configured credentials) and
cloud-proxy (the tool-calling client calls the Cloud Control Plane's
planner-decision endpoint, which calls the provider using cloud-held
credentials) -- selectable via configuration without requiring any change
to `AIPlanner`'s own decision logic.
#### Scenario: Provider selected via configuration
- **WHEN** the AI Planner is configured with a given provider identifier
- **THEN** it constructs and uses the tool-calling client for that provider
without requiring any change to `AIPlanner`'s own decision logic
#### Scenario: Provider response resolves to a single decision
- **WHEN** either supported provider returns a response to a tool-calling
request
- **THEN** the response is parsed into exactly one tool name and one
arguments object, regardless of which provider produced it
#### Scenario: Transport selected via configuration
- **WHEN** the Host Agent is configured with a given transport (direct or
cloud-proxy)
- **THEN** `AIPlanner` is constructed with the tool-calling client for that
transport, and its own decision logic is unchanged regardless of which
transport is in effect
#### Scenario: Direct transport remains available and default
- **WHEN** no transport is explicitly configured
- **THEN** the AI Planner uses the direct-to-provider transport, matching
its behavior before the cloud-proxy transport existed
#### Scenario: Cloud-proxy transport resolves a decision without a local provider client
- **WHEN** the Host Agent is configured with the cloud-proxy transport
- **THEN** its tool-calling client sends the decision request to the Cloud
Control Plane's planner-decision endpoint instead of constructing a local
Anthropic or OpenAI SDK client
@@ -0,0 +1,59 @@
## ADDED 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.
#### 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
### 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