apomesh-orchestrator

apomesh-orchestrator is the orchestrator layer: the control-plane gRPC daemon that implements the ApomeshDaemon service, plus the substrate-side OrchestratorRuntime that holds session state and coordinates dispatch. It follows substrate-first discipline — the gRPC handler is a thin adapter that receives wire envelopes, calls into apomesh-substrate and the session coordinator, and emits responses; the business logic lives in the substrate crate. The crate is a library split from its binary (which lives in apomesh-orchestrator-bin) so integration tests construct the same daemon the binary serves. Touch it for control-plane behaviour: the RPC surface, the session workflow, cost aggregation, the coordinator seam.

Position in the workspace

• Layer: orchestrator. See The orchestrator and Coordination loops.
• Depends on: apomesh-protocol (the wire it serves), apomesh-substrate (with the mcp feature — the business logic it delegates to), and apomesh-substrate-catalog.
• Consumed by: apomesh-orchestrator-bin (the binary that wires the concrete strategies), the REST API, SmartChat, and both verticals (for the SessionEntry coordinator seam).

What it owns

• OrchestratorDaemon — the ApomeshDaemon gRPC service impl; its handlers translate-and-delegate to the substrate.
• OrchestratorRuntime — the session-state holder and dispatch coordinator that outlives any single RPC.
• The transport-blind session workflow — create_session_workflow, the substrate-side entry both the gRPC handler and the REST route call.
• The coordinator seam — the SessionEntry trait and SessionStrategyRegistry (one coordinator per session; skeletons compose only by nesting sub-sessions).
• Cost aggregation, the agent tree, and built-in coordinators — CostAggregator / TenantCostAggregator, the reconstructed AgentTree, and the debate / parallel-sample multi-coordinator skeletons.

Public surface

• OrchestratorDaemon — the daemon struct and ApomeshDaemon service impl; built via OrchestratorDaemon::new() plus builder methods (with_registry, with_session_auth, with_worker_auth, with_agent_catalog).
• OrchestratorDaemon::create_session_workflow — the transport-blind session-create entry; takes a TenantContext + StartSessionRequest, returns a typed outcome. gRPC and REST both delegate here.
• OrchestratorRuntime — per-session state, the agent roster, in-flight dispatches, and the event log.
• SessionEntry (trait) + SessionStrategyRegistry — the coordinator seam and the registry that binds a SessionKind to its coordinator.
• CostAggregator / TenantCostAggregator — session-scoped and tenant-scoped cost rollups derived from the event log.
• AgentTree / AgentNode — the spawn tree reconstructed from SpawnRequest / NodeCompleted events.
• GrpcOrchestratorDispatch — the worker-facing dispatch bridge.
• DebateCoordinator — a built-in coordinator skeleton over the shared governed core.
• LoopEngineCoordinator — the generic engine: one SessionEntry that runs any LoopDefinition, with the session-scope participant binding and engine services beside it. The parallel-sample kind is a definition it runs — a config and a mapping onto that definition, with no coordinator of its own.

Usage

OrchestratorDaemon::new() builds a default daemon (null auth, no strategy registry) — the shape a test fixture uses; production layers the registry and auth backends on with the builder methods.

use apomesh_orchestrator::OrchestratorDaemon;

// A default daemon: `NullSessionAuth`, no registry. Production wires a
// `SessionStrategyRegistry` and real auth via `with_registry` /
// `with_session_auth` before serving.
let daemon = OrchestratorDaemon::new();

Related

• Concepts: The orchestrator, Sessions, events & durability, Coordination loops.
• Reference: apomesh-substrate (the business logic it delegates to), apomesh-protocol (the wire it serves).