37 lines
3.6 KiB
Markdown
37 lines
3.6 KiB
Markdown
## 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.
|