.nornir/agent-pool-design.md · nordisk/dwarves

agent pool — design

Class: design · Function axis: f0 the fleet-as-data surface (the whole) · f1 the AgentPool RPC · f2 the dwarves agents verb (fat + thin) · f3 the jera reuse seam Strict: this file states only what the agent-pool surface IS — its parts and why. Sibling how-to: agent-pool-guide.md; zero-knowledge walkthrough: agent-pool-for-idiots.md.

The agent pool surface exposes the worker fleet the forge dispatches to — every registered agent (id, group, capabilities, cores/mem, liveness) — as data, over the wire and from the CLI. It closes the D1-wishlist gap "AgentPool … remain open" and is the enabling wire for the parity §4b "Agents view — the live fleet." Before this, Show/History carried pipelines + runs but the fleet was invisible over gRPC.

The system as one — the function map (f0)

part	lives in	what it is
`f1` `AgentPool` RPC	`crates/dwarves/src/server.rs` · `proto/dwarf.proto`	`DwarfSvc::agent_pool` reads the shared jera `Scheduler` → `AgentPoolReply{ repeated AgentRow }`
`f2` `dwarves agents` verb	`crates/dwarves/src/main.rs`	fat = the local single-machine pool; thin = the server's live pool over `AgentPool`
`f3` reuse seam	jera (edda)	`Scheduler::state_json()` — the ONE fleet-as-data contract, consumed not twinned

Why it is shaped this way

Reuse jera's fleet contract (Law #1). dwarves owns no scheduler of its own — the Agent/Scheduler/worker-group machinery lives in jera::agent (edda). The RPC handler reads Scheduler::state_json() (the documented {agents:[{id,group,caps, cores,mem_mb,state}]} shape jera already ships for exactly this "feed a UI Agents pane" purpose) and maps each row onto the wire — no internal accessor, no twin fleet model. The fat CLI reads the same state_json() from the local default pool, so fat and thin print an identical listing.
One surface, single→multi machine. The pool is LocalAgent single-machine today (scheduler_with_local_default seeds local-0 in group default, cap cargo). A GrpcAgent fleet registers into the SAME Scheduler, so AgentPool reports a real multi-machine fleet with no change to this surface — the lazy-but- seam-honest discipline the parity spec mandates for distribution.
Additive + gated like every RPC. The AgentPool RPC + thin_agents client compile only under --features server (proto codegen + tonic); the fat dwarves agents needs only agent_bridge (always compiled). nornir's lean path-dep pulls nothing new.
Observed as data (L4). The handler is drive-and-assert tested (a fresh server's pool is exactly local-0/default/cargo/idle, RED-when-broken) with a dwarves::server / agent_pool testmatrix cell. No new UI surface ⇒ no robot row (the fleet-as-data contract is the assertion, same as the Badge RPC).

Place in the nordisk constellation

This is a dwarves-owned control-plane surface reading a shared jera primitive. It mirrors the constellation's "expose the fleet as data so a robot/matrix can assert it" law: nornir, dwarves and holger all get multi-machine awareness from the one jera crate, and each surfaces its pool the same way. The eventual Agents pane (facett-jobview-adjacent) consumes this RPC behind the same state_json shape.

Deferred

No Agents UI pane yet. The RPC + CLI land the wire; mounting a live Agents pane in dwarves-gui (over this RPC or a fixture) is a follow-up, mirroring the Status-board build-out.
Single in-process agent. Only the default LocalAgent is registered today; the GrpcAgent remote-registration path (a <host> dwarves agent --group … joining the server's scheduler over gRPC) is the tracked multi-machine leg — this surface already reports whatever the scheduler holds, so it needs no change when that lands.
PDFs (docs/*.pdf) left for the Loki bencher's nornir docs book render.