113 lines
7.0 KiB
Markdown
113 lines
7.0 KiB
Markdown
# 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 active database-managed Provider profile's timeout. The endpoint SHALL resolve the active 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
|
|
|
|
#### Scenario: Host supplies a different timeout
|
|
- **WHEN** a Host Agent's planner-decision request carries a timeout that differs
|
|
from the active Provider profile
|
|
- **THEN** the Cloud Control Plane uses the active Provider profile's timeout
|
|
for the provider call
|
|
|
|
### 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: Cloud Control Plane persists each resolved planner decision for later retrieval
|
|
The Cloud Control Plane SHALL, for each planner-decision request it successfully resolves to a tool-call decision, persist the request's system prompt, user prompt, resolved tool name and arguments, and an assigned step index scoped to the request's `task_id` and `attempt`, in addition to returning the decision to the requesting Host Agent. The Cloud Control Plane SHALL NOT persist screenshot bytes from these requests.
|
|
|
|
#### Scenario: A planner-decision request resolves successfully
|
|
- **WHEN** the Cloud Control Plane resolves a planner-decision request with task
|
|
context to a tool-call decision
|
|
- **THEN** it persists the request's system prompt, user prompt, resolved tool
|
|
name and arguments, and a step index for that task and attempt before
|
|
returning the decision to the Host Agent
|
|
|
|
#### Scenario: A planner-decision request fails
|
|
- **WHEN** the configured provider call fails and the endpoint returns a
|
|
structured failure response
|
|
- **THEN** no planner-decision row is persisted for that request
|
|
|
|
#### Scenario: A screenshot was included in the request
|
|
- **WHEN** a planner-decision request includes a screenshot
|
|
- **THEN** the screenshot bytes are used only to call the LLM provider and are
|
|
not written to the persisted decision log
|
|
|
|
### Requirement: Persisted planner decisions are retained within a bounded window
|
|
The Cloud Control Plane SHALL prune persisted planner decisions once their owning task has been in a terminal state for longer than a configurable retention window, so that indefinite operation does not cause unbounded growth of the decision log.
|
|
|
|
#### Scenario: A task's retention window has elapsed since reaching a terminal state
|
|
- **WHEN** a task reached a terminal state more than the configured retention
|
|
window ago
|
|
- **THEN** the Cloud Control Plane removes that task's persisted planner
|
|
decisions
|
|
|
|
#### Scenario: A task is still active or within its retention window
|
|
- **WHEN** a task is still active, or reached a terminal state less than the
|
|
configured retention window ago
|
|
- **THEN** its persisted planner decisions remain available for query
|
|
|
|
### Requirement: Cloud-side planner decision history is scoped to cloud-proxy transport
|
|
The Cloud Control Plane's persisted planner-decision log SHALL contain entries only for Hosts whose planner calls were routed through cloud-proxy transport; it SHALL NOT contain entries, synthesized or otherwise, for Hosts using direct-to-provider transport.
|
|
|
|
#### Scenario: A Host uses direct-to-provider transport
|
|
- **WHEN** a Host Agent configured for direct-to-provider transport executes an
|
|
assignment
|
|
- **THEN** no planner-decision entries for that assignment appear in the Cloud
|
|
Control Plane's persisted decision log
|
|
|
|
### 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
|