feat(cloud): add targeted task governance foundation

2026-07-13 22:21:12 +08:00
parent a3ba94be04
commit 2cd314b183
41 changed files with 2099 additions and 15 deletions
@@ -0,0 +1,84 @@
+## 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