Report unbounded node load as unmeasured

Merged
KJ
2mo ago
+174-15

What changed

  • represent broker heartbeat load as optional
  • omit load when max_agents == 0 instead of emitting a false 0
  • keep finite capacity utilization as active_agents / max_agents, clamped and validated in [0,1]
  • add wire and calculation coverage for a 25-agent unbounded node and a finite 3/4 node
  • verify the Relay SDK translates Relaycast load: null into an absent optional field, so agent-relay fleet nodes cannot render unknown utilization as zero

Root cause

The broker already measured active_agents from the live worker map and read an optional finite capacity from AGENT_RELAY_NODE_MAX_AGENTS. Runtime state intentionally normalized an absent capacity to max_agents: 0 (unlimited), but FleetLoadSnapshot::heartbeat then substituted 0.0 for the undefined ratio. That made “not measured” indistinguishable from “measured idle” all the way through the fleet roster.

load now means only managed-agent capacity utilization. It is numeric in [0,1] when a finite positive maximum exists and absent for an unlimited node. It does not represent CPU, memory, queue depth, or dispatch latency.

Compatibility and deployment order

Companion Relaycast PR: https://github.com/AgentWorkforce/relaycast/pull/307

Relaycast must land and deploy first so the server accepts omitted/null load and persists it honestly. This PR must not be deployed independently before that compatibility layer is live.

Validation

  • broker heartbeat calculation test passed
  • broker fleet-wire heartbeat tests passed (finite, absent, negative, non-finite, and >1 cases)
  • Rust formatting check passed
  • Relay SDK messaging test passed (20 tests)
  • Relay SDK TypeScript typecheck passed

No deployment or merge is included.