80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
## Why
|
|
|
|
The Cloud Console can currently inspect distributed work but cannot direct
|
|
that work to a selected Host or Device, govern who may submit it, or explain
|
|
and control the AI spend generated by each Host. Now that
|
|
`cloud-planner-proxy` is planned to centralize the LLM call path, the next
|
|
control-plane increment can make those operational decisions enforceable at
|
|
the Cloud boundary instead of trusting every edge process to self-govern.
|
|
|
|
## What Changes
|
|
|
|
- Add Console task creation for authorized operators, with explicit target
|
|
selectors for a Host and optionally one of that Host's Devices. A selected
|
|
target is a hard scheduling constraint and is never silently rerouted to a
|
|
different Host or Device.
|
|
- Add persisted Cloud governance policies: user submission restrictions
|
|
(submission enablement and allowed Host/Device targets) and versioned
|
|
per-Host operational/AI-budget policies. The API remains authoritative;
|
|
Console visibility is not an authorization boundary.
|
|
- Let a Host retrieve its current policy through the authenticated outbound
|
|
protocol, with version-aware heartbeat synchronization and a safe cached
|
|
representation for local visibility.
|
|
- Add a Host-scoped internal task-submission operation. An authenticated
|
|
Host can create a task only for itself and, when specified, one of its own
|
|
enrolled Devices; it never receives general public `tasks:submit` power.
|
|
- After `cloud-planner-proxy` is implemented and a Host uses its `cloud`
|
|
planner transport, record provider-reported token usage per Host/task/
|
|
attempt and enforce configured token budgets with atomic reservation and
|
|
settlement. Direct-to-provider Hosts remain explicitly unmetered and
|
|
cannot be represented as hard-budget-enforced.
|
|
- Extend the Console with task-creation, user-policy, Host-policy, and
|
|
per-Host AI-usage/budget views. Existing user lifecycle management remains
|
|
role-gated and gains policy editing rather than a new custom-role system.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
- `cloud-governance`: Durable, versioned user and Host policies that restrict
|
|
task submission/targets and define Host operational and AI-budget limits.
|
|
- `host-scoped-task-submission`: Authenticated internal operation that lets a
|
|
Host submit tasks constrained to itself.
|
|
- `cloud-ai-usage-governance`: Durable AI usage metering, budget reservations,
|
|
settlement, and non-secret reporting for Cloud-proxied planner calls.
|
|
|
|
### Modified Capabilities
|
|
|
|
- `cloud-console-ui`: add governed task creation and operational governance
|
|
views to the existing Cloud Console experience. This capability is still
|
|
defined by active Console changes and will be reconciled before archive.
|
|
- `platform-sdk`: extend public task submission/status and `CloudClient`
|
|
parity with explicit task targets and safe governance-facing responses.
|
|
- `task-scheduler`: make explicit Host/Device target selectors part of task
|
|
constraints and enforce them during matching.
|
|
- `host-agent-protocol`: return versioned Host policy through the outbound
|
|
protocol and add Host-self task submission while retaining host binding.
|
|
- `cloud-planner-proxy`: enforce Host budget reservations and emit
|
|
provider-reported usage only after the proxy change is implemented. This
|
|
capability is currently an active, unarchived change.
|
|
- `agent-runtime`: carry provider-reported non-secret token usage alongside a
|
|
tool-call decision so the Cloud proxy can meter the call without changing
|
|
`AIPlanner` decision semantics. This capability is also active and
|
|
unarchived.
|
|
|
|
## Impact
|
|
|
|
- `packages/cloud-platform/cloud`: governance and usage domain models,
|
|
repository port/SQLAlchemy implementation, Alembic migration, scheduler
|
|
matching, public/internal Pydantic contracts, policy-aware authorization,
|
|
and proxy metering.
|
|
- `apps/cloud-api`: router composition and configuration only; all durable
|
|
policy and accounting behavior remains in the Cloud Platform package.
|
|
- `apps/device-host-agent`: policy-aware client/heartbeat state and
|
|
self-targeted task submission; no inbound Cloud connection is introduced.
|
|
- `cloud-console/`: task composer plus user/Host policy and AI-usage views.
|
|
- Dependencies and rollout: implementation is blocked until
|
|
`cloud-planner-proxy` is completed, its migration is deployed, and affected
|
|
Hosts are using `AI_PLANNER_TRANSPORT=cloud`; it also follows completion of
|
|
the active Cloud Console user-authentication work.
|