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

Why

The Cloud Control Plane (apps/cloud-api + packages/cloud-platform/cloud) is reachable only through its versioned REST/SDK surface — there is no Web UI. An operator who wants to see queue backlog, device/host health, or plugin registrations today has to script calls against /v1/* or query the database directly. Now that cloud-control-plane-integration has landed and archived the remote scheduling/lease/Host Agent loop, the missing operational visibility layer is the clearest gap left before this control plane is easy to run day-to-day. The existing console/ SPA does not cover this: it talks only to the local single-device Runtime API (port 8000), not the Cloud Control Plane (port 8001, scoped bearer auth).

What Changes

• Add a task listing endpoint (GET /v1/tasks, tasks:read scope) returning tasks across all statuses with status filtering and bounded pagination — today only POST /v1/tasks (submit) and GET /v1/tasks/{id} (single lookup) exist; the repository itself only exposes list_queued_tasks() (queued-only, used internally by the scheduler).
• Add a task attempt-history endpoint (GET /v1/tasks/{task_id}/attempts, tasks:read scope) exposing the already-implemented CloudRepository.list_task_attempts(), which today has no route at all.
• Extend the Python CloudClient with corresponding methods for both new endpoints, preserving platform-sdk's existing requirement that the client mirrors every /v1/... route.
• Add an independent Web console frontend (new cloud-console/ Vue 3 + Vite SPA at the repo root, sibling to the existing console/) that authenticates with an operator-supplied bearer token (pasted in, held client-side) and renders:
  • a task queue/history view (list + filter by status, detail with attempt history),
  • a device pool and host registry view (including staleness/unreachable status),
  • a plugin registry view with a form to submit a new plugin manifest (POST /v1/plugins).
• Explicitly out of scope: task cancellation or retry-from-UI (no such scheduler operation exists), Host Agent remote start/stop (Host Agent only makes outbound calls; the control plane cannot push commands to it), plugin de-registration (no repository method exists), and any login/session/RBAC system beyond pasting a pre-issued scoped bearer token (mirrors how CloudClient already authenticates — no new auth mechanism).

Capabilities

New Capabilities

• cloud-console-ui: Independent Vue 3 + Vite SPA for the Cloud Control Plane, consuming the platform SDK's /v1 REST surface (existing endpoints plus the two added by this change) to provide read dashboards for tasks/devices/hosts/plugins and a plugin-registration action, authenticated via an operator-supplied bearer token.

Modified Capabilities

• platform-sdk: add task listing (GET /v1/tasks, filterable/paginated) and task attempt-history (GET /v1/tasks/{task_id}/attempts) requirements to the existing versioned /v1 surface, both scope-gated by tasks:read; extend the CloudClient requirement so it continues to mirror every route.

Impact

• New code: routes and response models in packages/cloud-platform/cloud/sdk/api.py / cloud/sdk/models.py; a new bounded/filtered task-listing method on CloudRepository (repository.py Protocol) implemented in sql_repository.py; new CloudClient methods in cloud/sdk/client.py; a new top-level cloud-console/ Vue 3 + Vite SPA project (own package.json/build, no Python dependency).
• Modified code: cloud/sdk/api.py router gains two GET routes; no change to existing submission, assignment, claim, renewal, or result-recording behavior.
• Dependencies: no new backend dependency (reuses FastAPI/Pydantic already in packages/cloud-platform); the new frontend brings its own Node/Vue 3/Vite toolchain, matching the existing console/ project's pattern.
• Docs: docs/CLOUD_DEPLOYMENT.md gains a section on running the console and obtaining/rotating an operator bearer token for it.