agentic-mobile-control/openspec/changes/cloud-console-governance/proposal.md

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.