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

ADDED Requirements

Requirement: Task listing via the SDK

The system SHALL allow an external integrator to list tasks known to the task-scheduler capability across all statuses, through the platform SDK's API, with optional status filtering and bounded pagination.

Scenario: List tasks without a filter

• WHEN an integrator with tasks:read calls the task-listing endpoint with no status filter
• THEN the API returns tasks across all statuses, most recently created first, bounded to the requested (or default) page size

Scenario: List tasks filtered by status

• WHEN an integrator calls the task-listing endpoint with a status filter (e.g. failed)
• THEN the API returns only tasks currently in that status

Scenario: Page size exceeds the maximum

• WHEN an integrator requests a page size above the API's configured maximum
• THEN the API rejects the request rather than returning an unbounded result set

Requirement: Task attempt history via the SDK

The system SHALL allow an external integrator to retrieve the attempt history of a known task — each attempt's assignment, lease, and terminal outcome — through the platform SDK's API, backed by the task-scheduler capability's attempt records.

Scenario: Retrieve attempt history for a known task

• WHEN an integrator with tasks:read requests the attempt history for a task id that exists
• THEN the API returns every recorded attempt for that task in chronological order, including its outcome

Scenario: Retrieve attempt history for an unknown task

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

MODIFIED Requirements

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, list tasks, get task attempt history, 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 lists tasks and retrieves attempt history

• WHEN a caller uses CloudClient to list tasks with a status filter and then fetch attempt history for one returned task id
• THEN the client's methods produce the same result as calling the corresponding /v1/... endpoints directly over HTTP