5.2 KiB
ADDED Requirements
Requirement: Host identity is authenticated and bound to one host id
The internal Host Agent API SHALL require a host-scoped bearer principal and SHALL reject any request that attempts to act for a host_id different from the authenticated principal's bound host.
Scenario: Host authenticates as itself
- WHEN a Host Agent presents valid credentials bound to its requested
host_id - THEN the internal API authorizes permitted heartbeat, claim, renewal, and result operations
Scenario: Host attempts to impersonate another host
- WHEN valid credentials bound to host A are used on a request for host B
- THEN the internal API rejects the request without reading or modifying host B's state
Requirement: Host Agent synchronizes heartbeat and complete device snapshots
The Host Agent SHALL periodically submit its complete local device snapshot to the control plane, and the control plane SHALL atomically refresh the host heartbeat and replace only that host's pooled-device records.
Scenario: Host reports devices
- WHEN a Host Agent submits a valid heartbeat containing its current devices
- THEN the control plane updates the host's last-seen time and exposes the submitted devices through the aggregated pool
Scenario: Host reports no devices
- WHEN a previously populated host submits an empty device snapshot
- THEN only that host's prior device records are removed while devices owned by other hosts remain unchanged
Requirement: Host Agent receives work through outbound long-polling
The Host Agent SHALL request assigned work for its own host through a configurable long-poll endpoint, and the control plane SHALL return at most one atomically claimable assignment per response or an empty timeout response.
Scenario: Assigned work is available
- WHEN a Host Agent long-polls and an unclaimed assignment exists for its host
- THEN the control plane atomically transitions the assignment to dispatched and returns its task, device, attempt, lease, and execution payload
Scenario: No work becomes available
- WHEN no assignment for the host becomes available before the configured poll timeout
- THEN the endpoint returns a normal empty response and the Host Agent may poll again with backoff
Requirement: Active execution renews its lease
The Host Agent SHALL renew the active assignment lease before expiry while execution continues, and SHALL treat loss or rejection of the lease as a stop condition for further planned actions where interruption is possible.
Scenario: Lease renewal succeeds
- WHEN the owning Host Agent renews an unexpired active lease
- THEN the control plane extends its expiry without changing the task attempt or device assignment
Scenario: Lease is stale or foreign
- WHEN a Host Agent attempts to renew an expired, replaced, or differently owned lease
- THEN the control plane returns a conflict and does not revive or alter the current attempt
Requirement: Host execution composes existing Runtime and workflow runners
The Host Agent SHALL execute goal assignments through the existing TaskRunner and workflow assignments through the existing WorkflowRunner, using its local DeviceManager and Runtime configuration rather than reimplementing execution behavior.
Scenario: Execute a goal assignment
- WHEN the Host Agent claims a goal-based assignment for a connected local device
- THEN it runs a
Taskthrough the configured Runtime Planner/Executor loop and captures the terminal status and failure reason
Scenario: Execute a workflow assignment
- WHEN the Host Agent claims an assignment referencing an available workflow definition
- THEN it invokes the existing workflow runner for the assigned device and captures the terminal workflow outcome
Requirement: Terminal result reporting is idempotent
The Host Agent SHALL report a terminal result using the task, attempt, and lease identifiers, and repeating the same report SHALL return the already recorded outcome without duplicating state transitions.
Scenario: Report a successful result
- WHEN the active lease owner reports successful completion
- THEN the control plane marks the scheduled task done, releases the device reservation, and records the result metadata
Scenario: Retry a result after response loss
- WHEN the Host Agent repeats the identical terminal report for an already completed active lease
- THEN the control plane returns the recorded terminal result without creating a new attempt or error
Scenario: Stale attempt reports after requeue
- WHEN an expired earlier attempt reports after a newer attempt has been created
- THEN the control plane rejects the stale report and preserves the newer attempt's state
Requirement: Host operation requires no inbound cloud connection
The Host Agent SHALL perform synchronization, work retrieval, lease renewal, and result reporting using outbound requests only.
Scenario: Host is behind NAT
- WHEN the Host Agent can reach the control-plane URL but exposes no inbound listener
- THEN it can register devices and execute cloud assignments through the complete protocol