agentic-mobile-control/openspec/changes/cloud-control-plane-integration/proposal.md

Why

The existing cloud package models hosts, pooled devices, queued tasks, plugins, and an SDK, but it has no runnable control-plane composition, no network path for hosts to synchronize devices, and explicitly rejects assignments targeting another process. This change turns those isolated modules into a deployable single-control-plane, multi-host execution loop while reusing the existing Runtime and completed AI Planner integration.

What Changes

• Add independently runnable cloud-api and device-host-agent uv workspace applications on top of the packaging boundaries established by uv-workspace-packaging.
• Add a Cloud Control Plane FastAPI application that composes the existing pool, scheduler, store, plugin registry, and public /v1 SDK router and runs scheduler/lease-maintenance loops through application lifespan.
• Add an authenticated Host Agent protocol for host registration, heartbeat/device snapshot synchronization, long-poll task claiming, lease renewal, and terminal result reporting.
• Replace the local-only remote-dispatch rejection with lease-backed execution by the Host Agent, which invokes the existing TaskRunner or WorkflowRunner on the owning device host.
• Add atomic assignment/claim semantics, active-device reservation, lease expiry, retry/requeue policy, idempotent result reporting, and process-restart recovery.
• Add PostgreSQL-backed cloud persistence with migrations for deployed environments while retaining SQLite for local development and tests behind the same store contract.
• Replace anonymous-by-default public API access with configured bearer-token authentication; use separately scoped credentials for public integrators and Host Agents.
• Add health/readiness endpoints, structured operational logging, and configuration validation suitable for container deployment.
• BREAKING: the platform SDK API no longer allows anonymous access by default; startup requires an explicit development override or configured credentials.

Capabilities

New Capabilities

• cloud-control-plane: Runnable cloud application composition, lifecycle workers, deployable persistence, health checks, and restart recovery.
• host-agent-protocol: Authenticated outbound Host Agent synchronization, leased task delivery, execution reporting, and failure recovery.

Modified Capabilities

• device-pool: Host registrations and device snapshots become reachable through the authenticated Host Agent protocol while retaining staleness behavior.
• task-scheduler: Remote assignments become lease-backed, remotely executable work with atomic claim, reservation, expiry, and retry semantics instead of being rejected.
• platform-sdk: Public cloud routes require configured authentication by default and expose stable task lifecycle outcomes from the distributed execution loop.

Impact

• Depends on completion of uv-workspace-packaging and adds workspace members under apps/cloud-api and apps/device-host-agent.
• Extends the extracted cloud platform package, cloud database schema, configuration, SDK models/client, and deployment documentation.
• Adds PostgreSQL driver and migration dependencies for cloud deployments; SQLite remains supported for local/test operation.
• Host Agent execution composes existing DeviceManager, TaskRunner, WorkflowRunner, and the production Planner selected by Runtime configuration; it does not move transport concerns into core, driver, device, or tools.
• Does not add multi-tenancy, billing, a user-management UI, arbitrary inbound connections to device hosts, or a separate message broker in this change.