chore(openspec): archive task execution visibility
This commit is contained in:
@@ -1,64 +1,136 @@
|
||||
# host-agent-dependency-supervisor Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how the Host Agent optionally supervises its own dependencies (Appium and the local Runtime API), including opt-in activation, adoption of already-running healthy instances, bounded-restart lifecycle for spawned processes, and cleanup tied to the Host Agent's own process lifecycle.
|
||||
Define optional Appium supervision by the Host Agent, including opt-in
|
||||
activation, adoption of healthy instances, bounded restart behavior, and
|
||||
cleanup tied to the Host Agent lifecycle.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Supervisor is opt-in and disabled by default
|
||||
The Host Agent SHALL NOT start, adopt-check, or supervise Appium or the local Runtime API unless `HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED` is explicitly set to true. Each of the two dependencies SHALL additionally have its own independent enable flag (`HOST_AGENT_APPIUM_SUPERVISED`, `HOST_AGENT_RUNTIME_SUPERVISED`), both defaulting to false.
|
||||
|
||||
The Host Agent SHALL NOT start, adopt-check, or supervise Appium unless
|
||||
`HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED` is explicitly set to true. Appium
|
||||
supervision SHALL additionally require `HOST_AGENT_APPIUM_SUPERVISED=true`
|
||||
and SHALL default to false.
|
||||
|
||||
#### Scenario: Default configuration behaves exactly as before
|
||||
- **WHEN** a Host Agent starts with no `HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED` (or any related) environment variable set
|
||||
- **THEN** the Host Agent does not attempt to connect to, probe, or spawn Appium or the Runtime API, and its heartbeat/claim behavior is unchanged from before this capability existed
|
||||
|
||||
#### Scenario: Top-level flag on, individual dependency flag off
|
||||
- **WHEN** `HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED=true` and `HOST_AGENT_APPIUM_SUPERVISED=false` (Runtime supervised is true)
|
||||
- **THEN** the Host Agent supervises only the Runtime API and does not probe, adopt, or spawn Appium
|
||||
- **WHEN** a Host Agent starts with no
|
||||
`HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED` or related Appium environment
|
||||
variable set
|
||||
- **THEN** the Host Agent does not attempt to connect to, probe, or spawn
|
||||
Appium, and its heartbeat/claim behavior is unchanged
|
||||
|
||||
### Requirement: Adopt an already-running, healthy dependency instead of spawning a duplicate
|
||||
Before spawning a supervised dependency, the Host Agent SHALL attempt a TCP connection to its configured host/port, and if something is listening, SHALL perform the dependency-specific health check (Appium: HTTP GET to its status endpoint expecting a successful response; Runtime: HTTP GET to its health endpoint expecting a successful response). If the health check succeeds, the Host Agent SHALL treat the existing process as adopted, SHALL NOT spawn a subprocess for that dependency, and SHALL NOT restart or terminate the adopted process at any point in its lifecycle.
|
||||
#### Scenario: Top-level flag on and Appium flag off
|
||||
|
||||
- **WHEN** `HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED=true` and
|
||||
`HOST_AGENT_APPIUM_SUPERVISED=false`
|
||||
- **THEN** the Host Agent does not probe, adopt, or spawn Appium
|
||||
|
||||
### Requirement: Adopt an already-running, healthy Appium instance instead of spawning a duplicate
|
||||
|
||||
Before spawning supervised Appium, the Host Agent SHALL attempt a TCP
|
||||
connection to its configured host and port and, if something is listening,
|
||||
perform the Appium status health check. If the health check succeeds, the Host
|
||||
Agent SHALL treat the existing process as adopted, SHALL NOT spawn a subprocess
|
||||
for it, and SHALL NOT restart or terminate it at any point in its lifecycle.
|
||||
|
||||
#### Scenario: Appium already running and healthy
|
||||
- **WHEN** Appium supervision is enabled and a healthy Appium server is already listening on the configured host/port
|
||||
- **THEN** the Host Agent logs that it adopted the existing instance and does not spawn a new Appium process
|
||||
|
||||
- **WHEN** Appium supervision is enabled and a healthy Appium server is already
|
||||
listening on the configured host and port
|
||||
- **THEN** the Host Agent logs that it adopted the existing instance and does
|
||||
not spawn a new Appium process
|
||||
|
||||
#### Scenario: Port occupied by something unhealthy or unrelated
|
||||
- **WHEN** a supervised dependency's port has a listener that does not pass the dependency-specific health check
|
||||
- **THEN** the Host Agent logs an error identifying the port conflict for that dependency and does not spawn a subprocess for it, and does not treat the dependency as available
|
||||
|
||||
### Requirement: Spawn supervised dependencies that are not already running
|
||||
When a dependency is enabled for supervision and no healthy instance is adopted, the Host Agent SHALL spawn it as a child process (Appium via `appium --address <host> --port <port>`; Runtime API via its existing `uvicorn api.rest:create_app --factory` entry point with the configured host/port), and SHALL forward the child process's stdout/stderr into the Host Agent's own logging, tagged by dependency name.
|
||||
- **WHEN** the configured Appium port has a listener that does not pass the
|
||||
health check
|
||||
- **THEN** the Host Agent logs an error identifying the port conflict, does
|
||||
not spawn a subprocess, and does not treat Appium as available
|
||||
|
||||
#### Scenario: Neither dependency is running at Host Agent startup
|
||||
- **WHEN** both Appium and Runtime supervision are enabled and neither has a healthy instance already listening
|
||||
- **THEN** the Host Agent spawns both as child processes before proceeding to its first device-connect attempt, and both processes' output is visible in the Host Agent's logs
|
||||
### Requirement: Spawn supervised Appium when it is not already running
|
||||
|
||||
The Host Agent SHALL spawn Appium as a child process when Appium supervision is
|
||||
enabled and no healthy Appium instance is adopted, via
|
||||
`appium --address <host> --port <port>`, and SHALL forward the child
|
||||
process's stdout/stderr into the Host Agent's own logging, tagged by dependency
|
||||
name.
|
||||
|
||||
#### Scenario: Appium is not running at Host Agent startup
|
||||
|
||||
- **WHEN** Appium supervision is enabled and no healthy Appium instance is
|
||||
already listening
|
||||
- **THEN** the Host Agent spawns Appium before proceeding to its first
|
||||
device-connect attempt, and its output is visible in Host Agent logs
|
||||
|
||||
#### Scenario: Spawn fails because the executable is missing
|
||||
- **WHEN** the Host Agent attempts to spawn Appium but `appium` is not found on `PATH`
|
||||
- **THEN** the Host Agent logs a dependency-supervisor-specific startup error naming the missing dependency, distinct from a runtime crash of an already-started process
|
||||
|
||||
### Requirement: Restart only processes the supervisor itself spawned, with bounded backoff
|
||||
The Host Agent SHALL restart a supervised dependency automatically only if the Host Agent's own child process handle for it exits unexpectedly. Restart attempts SHALL use capped exponential backoff and SHALL stop permanently for that dependency, for the remaining lifetime of the current Host Agent process, once a configured maximum attempt count (`HOST_AGENT_DEPENDENCY_RESTART_MAX_ATTEMPTS`) is reached. The Host Agent SHALL NOT restart or terminate a dependency instance it adopted rather than spawned.
|
||||
- **WHEN** the Host Agent attempts to spawn Appium but `appium` is not found
|
||||
on `PATH`
|
||||
- **THEN** the Host Agent logs a dependency-supervisor-specific startup error
|
||||
naming the missing dependency, distinct from a runtime crash of an
|
||||
already-started process
|
||||
|
||||
### Requirement: Restart only Appium processes the supervisor itself spawned, with bounded backoff
|
||||
|
||||
The Host Agent SHALL restart supervised Appium automatically only if its own
|
||||
child process handle exits unexpectedly. Restart attempts SHALL use capped
|
||||
exponential backoff and SHALL stop permanently for the remaining Host Agent
|
||||
process lifetime once `HOST_AGENT_DEPENDENCY_RESTART_MAX_ATTEMPTS` is
|
||||
reached. The Host Agent SHALL NOT restart or terminate an Appium instance it
|
||||
adopted rather than spawned.
|
||||
|
||||
#### Scenario: Spawned Appium process crashes
|
||||
- **WHEN** a Host Agent-spawned Appium child process exits unexpectedly and the per-dependency restart attempt count is below the configured maximum
|
||||
- **THEN** the Host Agent waits the current backoff interval and attempts to spawn Appium again
|
||||
|
||||
- **WHEN** a Host Agent-spawned Appium child process exits unexpectedly and
|
||||
the restart attempt count is below the configured maximum
|
||||
- **THEN** the Host Agent waits the current backoff interval and attempts to
|
||||
spawn Appium again
|
||||
|
||||
#### Scenario: Restart attempts exhausted
|
||||
- **WHEN** a supervised dependency has crashed and been restarted until reaching `HOST_AGENT_DEPENDENCY_RESTART_MAX_ATTEMPTS`
|
||||
- **THEN** the Host Agent logs that it has given up restarting that dependency and does not attempt to spawn it again for the rest of the current process lifetime
|
||||
|
||||
#### Scenario: Adopted process exits
|
||||
- **WHEN** a dependency instance the Host Agent adopted (did not spawn) stops running
|
||||
- **THEN** the Host Agent does not attempt to restart it, since it never held a child process handle for it
|
||||
- **WHEN** a supervised Appium process has crashed and been restarted until
|
||||
reaching `HOST_AGENT_DEPENDENCY_RESTART_MAX_ATTEMPTS`
|
||||
- **THEN** the Host Agent logs that it has given up restarting Appium and does
|
||||
not attempt to spawn it again for the rest of the current process lifetime
|
||||
|
||||
#### Scenario: Adopted Appium exits
|
||||
|
||||
- **WHEN** an Appium instance the Host Agent adopted stops running
|
||||
- **THEN** the Host Agent does not attempt to restart it, since it never held
|
||||
a child process handle
|
||||
|
||||
### Requirement: Supervisor lifecycle is tied to Host Agent process lifecycle
|
||||
The Host Agent SHALL start enabled, not-yet-healthy supervised dependencies before beginning its normal device-connect/heartbeat/claim sequence, and SHALL stop any dependency processes it spawned (not ones it adopted) during its own graceful shutdown.
|
||||
|
||||
The Host Agent SHALL start enabled, not-yet-healthy supervised Appium before
|
||||
beginning its normal device-connect, heartbeat, and claim sequence, and SHALL
|
||||
stop Appium processes it spawned, but not ones it adopted, during graceful
|
||||
shutdown.
|
||||
|
||||
#### Scenario: Host Agent shuts down gracefully
|
||||
- **WHEN** the Host Agent receives a shutdown signal while it holds a child process handle for a spawned Appium instance
|
||||
- **THEN** the Host Agent terminates the spawned Appium child process as part of its own shutdown sequence
|
||||
|
||||
#### Scenario: Host Agent shuts down while an adopted dependency is running
|
||||
- **WHEN** the Host Agent shuts down and Appium was adopted (not spawned) rather than spawned by this Host Agent
|
||||
- **THEN** the adopted Appium process is left running, untouched, after the Host Agent exits
|
||||
- **WHEN** the Host Agent receives a shutdown signal while it holds a child
|
||||
process handle for a spawned Appium instance
|
||||
- **THEN** the Host Agent terminates that Appium child process as part of its
|
||||
shutdown sequence
|
||||
|
||||
#### Scenario: Host Agent shuts down while adopted Appium is running
|
||||
|
||||
- **WHEN** the Host Agent shuts down and Appium was adopted rather than spawned
|
||||
- **THEN** the adopted Appium process is left running, untouched, after the
|
||||
Host Agent exits
|
||||
|
||||
### Requirement: Runtime supervision settings are retired
|
||||
|
||||
The Host Agent SHALL reject `HOST_AGENT_RUNTIME_SUPERVISED`,
|
||||
`HOST_AGENT_RUNTIME_HOST`, and `HOST_AGENT_RUNTIME_PORT` because the
|
||||
standalone Runtime service no longer exists.
|
||||
|
||||
#### Scenario: A legacy Runtime supervision variable is set
|
||||
|
||||
- **WHEN** startup configuration includes any removed Runtime supervision
|
||||
variable
|
||||
- **THEN** configuration fails with an actionable migration error
|
||||
|
||||
Reference in New Issue
Block a user