agentic-mobile-control/openspec/changes/task-cancellation/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) through the platform SDK's API, to query that task's current status by id, and to request cancellation of that task by id, backed by the task-scheduler capability.

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: 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, failed, or cancelled)

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

Scenario: Cancel a known task via the API

• WHEN an integrator with the required scope calls the cancel endpoint for a task id that exists and is not already done or failed
• THEN the API accepts the request and the underlying task-scheduler records the cancellation per its immediate or collaborative rules for that task's current status

Scenario: Cancel an unknown task

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

Requirement: Public API operations enforce scopes

The public platform API SHALL require operation-specific scopes, including task submission, task cancellation, task reading, pool reading, plugin reading, and plugin administration.

Scenario: Submit token has task scope

• WHEN a principal with tasks:submit calls the task-submission endpoint
• THEN the request is authorized subject to normal task validation

Scenario: Submit-scoped token cancels a task

• WHEN a principal with tasks:submit calls the task-cancellation endpoint for any task id
• THEN the request is authorized; the platform SDK does not restrict cancellation to the task's original submitter, since no per-task submitter identity is tracked

Scenario: Read-only token attempts cancellation

• WHEN a principal that holds only tasks:read calls the task-cancellation endpoint
• THEN the API rejects the request before contacting the scheduler

Scenario: Non-admin token 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

Requirement: Python SDK client mirrors the REST API

The system SHALL provide a Python client (CloudClient) exposing methods corresponding to each /v1/... route (submit task, get task status, cancel task, list devices, list hosts, list plugins, register plugin), so integrators do not need to hand-construct HTTP requests.

Scenario: Client submits a task and retrieves status

• WHEN a caller uses CloudClient to submit a task and then fetch its status by the returned id
• THEN the client's methods produce the same result as calling the corresponding /v1/... endpoints directly over HTTP

Scenario: Client cancels a task

• WHEN a caller uses CloudClient to cancel a task by id
• THEN the client's method produces the same result as calling the cancel endpoint directly over HTTP