agentic-mobile-control/openspec/changes/cloud-console-governance/specs/platform-sdk/spec.md

MODIFIED Requirements

Requirement: Task submission and status via the SDK

The system SHALL allow an external integrator to submit a task (goal or workflow reference plus constraints and an optional explicit Host/Device target) through the platform SDK's API, and to query that task's current status by id, backed by the task-scheduler capability. A Device target MUST include its owning Host, and the status representation SHALL expose any explicit target separately from the eventual assignment.

Scenario: Submit a task via the API

• WHEN an integrator calls the task-submission endpoint with a valid goal and optional constraints
• THEN the API returns a task id that can be used to poll status, and the underlying task-scheduler records a new queued ScheduledTask

Scenario: Submit a task for one Host and Device

• WHEN a tasks:submit principal submits a valid target containing an eligible Host and Device it is permitted to use
• THEN the API records that exact target and the scheduler cannot assign the task outside it

Scenario: Device target lacks its Host

• WHEN an integrator submits a Device target without an owning Host
• THEN the API rejects the request before creating a task

Scenario: Query status of a known task

• WHEN an integrator requests status for a task id that exists
• THEN the API returns that task's current status (queued, assigned, dispatched, done, or failed) and its explicit target when present

Scenario: Query status of an unknown task

• WHEN an integrator requests status for a task id that does not exist
• THEN the API returns a not-found response rather than an unhandled server error

Requirement: Python SDK client mirrors the REST API

The system SHALL provide a Python client (CloudClient) exposing methods corresponding to every /v1/... resource, user-authentication, user-administration, and governance route, including targeted task submission and read-only Host AI-usage access, so integrators do not need to hand-construct HTTP requests.

Scenario: Client submits a targeted task and retrieves status

• WHEN a caller uses CloudClient to submit a task with an explicit target and then fetches status by the returned id
• THEN the client produces the same target and lifecycle result as direct REST calls

Scenario: Client administers governance with a scoped bearer

• WHEN a caller configures CloudClient with governance:admin and invokes a policy operation
• THEN the client sends that authentication and returns the corresponding non-secret policy representation

Requirement: Public API operations enforce scopes

The public platform API SHALL require operation-specific scopes for task submission, task reading, pool reading, plugin reading, plugin administration, user administration, governance reading, and governance administration, regardless of whether the principal came from a bearer credential or user session.

Scenario: Submit principal has task scope

• WHEN a bearer or user principal with tasks:submit calls the task-submission endpoint
• THEN the request is authorized subject to normal task validation and any effective user-submission policy

Scenario: Non-admin principal attempts plugin registration

• WHEN an authenticated principal without plugins:admin calls plugin registration
• THEN the API rejects the request before resolving or loading the plugin target

Scenario: Non-admin principal attempts user administration

• WHEN an authenticated principal without users:admin calls a user-administration endpoint
• THEN the API rejects the request before reading or changing protected user state

Scenario: Principal lacks governance administration scope

• WHEN an authenticated principal without governance:admin changes a user or Host policy
• THEN the API rejects the request before changing policy or usage state