agentic-mobile-control/openspec/changes/web-console/specs/console-config-api/spec.md

ADDED Requirements

Requirement: Register a device

The system SHALL expose POST /console/devices accepting driver_type, connection_info, and an optional name, persist the configuration, and register the device with the running DeviceManager. Unsupported driver_type values SHALL be rejected.

Scenario: Register a supported device

• WHEN an operator posts {"driver_type": "wda", "connection_info": {"server_url": "http://127.0.0.1:4723", "udid": "abc123"}} to POST /console/devices
• THEN the response is a 201 with the new device's id and status idle, the device appears in GET /console/devices, and its configuration is persisted

Scenario: Reject unsupported driver type

• WHEN an operator posts a device with driver_type not in the supported set (currently wda)
• THEN the response is a 400 and no device is registered or persisted

Requirement: Unregister a device

The system SHALL expose DELETE /console/devices/{device_id} that disconnects and removes the device from DeviceManager and deletes its persisted configuration, or returns a 404 if the device is unknown.

Scenario: Unregister a known device

• WHEN an operator calls DELETE /console/devices/{device_id} for a registered device
• THEN the response is a 204, the device no longer appears in GET /console/devices, and its persisted configuration is removed

Scenario: Unregister an unknown device

• WHEN an operator calls DELETE /console/devices/{device_id} for a device id that is not registered
• THEN the response is a 404

Requirement: Persisted devices reload on startup

The system SHALL re-register every persisted device configuration with DeviceManager automatically when the application starts, without requiring manual re-registration.

Scenario: Restart with previously registered devices

• WHEN the application starts and one or more device configurations exist in the persisted device config store
• THEN each persisted device appears in GET /console/devices immediately after startup, without any additional operator action

Requirement: View and update runtime parameters

The system SHALL expose GET /console/config returning current adjustable runtime parameters (currently the task runner's max_steps) and PUT /console/config to update them, applying the change to the running task runner immediately and persisting it across restarts.

Scenario: View current runtime parameters

• WHEN an operator calls GET /console/config
• THEN the response is a 200 including the current max_steps value

Scenario: Update max_steps

• WHEN an operator calls PUT /console/config with {"max_steps": 30}
• THEN the response is a 200 with the updated value, subsequently started tasks (and the next iteration of any in-flight task) use the new max_steps, and the value is persisted so it survives a restart

Scenario: Reject invalid runtime parameter value

• WHEN an operator calls PUT /console/config with a non-positive max_steps (e.g. 0 or -1)
• THEN the response is a 400 and the previous value remains in effect