Module host 

The world host: the daemon-side wrapper that owns a single PipelineWorld, maps stable run ids to ECS entities, and interleaves external control operations with driving the world - all on one task, so there is never any locking around the world.

Clients (a control socket, the TUI, the CLI) don’t hold entities - those are generational indices meaningful only inside the world. They address agents by run id. The host keeps the run_id → Entity map and turns each ControlOp into the corresponding PipelineWorld call, replying on the op’s oneshot channel.

The serve loop drives the world to quiescence, then parks until either an async result wakes it, a control op arrives, or shutdown is signalled - handling a control op and then re-driving to quiescence so its effect (a resume, a delivered message) is applied immediately.

Structs

SpawnArgs

The parameters for spawning an agent into the world. The runtime doesn’t know how to load blueprints or resolve tools - that policy lives in the Spawner the daemon installs - so this just carries the raw request.

WorldEventSink

A world resource holding a clone of the host’s WorldEvent broadcast sender, so ECS systems (e.g. the persistence drain) can push events - notably per-agent WorldEvent::Log lines - into the same stream the control transport serves. Absent in worlds that don’t stream (test / lev run), where systems that depend on it become no-ops.

WorldHost

Owns the world and the run-id map; drives the world and services control ops.

Enums

ControlOp

A control operation addressed to the host, each carrying a oneshot channel the host replies on. Agents are addressed by run id.

SubAgentOp

A world-access request from an agent’s tool lane. The sub-agent tools (spawn_agent/check_agent/send_to_agent/kill_agent) need the world and the Spawner, which only the host holds - the tool lane runs async, off the world. Each carries a oneshot reply, so the (sequential) tool lane blocks on the host applying it, mirroring the interaction hub.

WorldEvent

A change in the world, broadcast to subscribers (the HTTP/WS gateway) so they get pushed updates instead of polling. Emitted by the host as it drives the world; streamed over the control transport via ControlRequest::Subscribe.

Type Aliases

ForceTerminator

The daemon-installed last resort for cancelling a run the world cannot hold: given a run id, it forces that run’s on-disk state to a terminal status and reports whether a run directory existed to act on.

Reaper

The daemon-installed hook run just before a terminal agent’s entity is despawned (reaped). It receives the world and the entity while both are still valid, so the daemon can release per-agent resources the runtime doesn’t know about - tearing down the agent’s sandbox and dropping its tool state. Installed with WorldHost::set_reaper; a no-op when none is set.

Reloader

The daemon-installed function that pages a previously-unloaded run back into the world from its on-disk state: given a run id, it reloads the agent (its blueprint, tool state, context, stage) and returns the new entity, or None if there is no such resumable run on disk. Used for reload-on-demand - a control/sub-agent op targeting a run that isn’t currently in memory pages it in first via the host’s internal resolve-or-reload step. Installed with WorldHost::set_reloader.

SpawnPreprocessor

An async hook the host awaits before servicing a top-level Spawn control op, so the daemon can do async preparation the sync spawner can’t - e.g. lazily connecting the blueprint’s MCP servers into the shared pool so they’re warm by the time Spawner reads them. The returned future is 'static (it must clone anything it needs from the SpawnArgs). Installed with WorldHost::set_spawn_preprocessor; when none is set, spawns proceed straight to the spawner.

Spawner

The daemon-installed function that turns SpawnArgs into a live agent: loads the blueprint, resolves stages/tools, spawns into the world, and returns the new entity (the host records the run-id mapping). Returns Err with a human-readable message on failure.