Installation, selection, and authorization
- A package declares a static Manifest and Python entry point.
- A Run selects a concrete plugin instance.
- The compiler intersects Manifest requests, Run access, and deployment ceilings into a final binding.
Plugin Host creates an instance only after all three. An installed but unselected package is not imported or started.
Four roles
| Role | Typical plugins | Responsibility |
|---|---|---|
control_producer |
Rule-based, Model, Teleop, Replay, Agent | Read authorized state and submit control chunks |
data_consumer |
Record, evaluation, monitoring | Consume events, observations, and outputs |
extension |
Geometry, kinematics, project capabilities | Add behavior at a stable service boundary |
interface |
Server, TUI, Debug, MCP | Present the same Application to users or systems |
A plugin may have multiple roles, but services are still granted individually.
Scoped services
Services include scenario.read, scene, frames, planning geometry, kinematics, observations, control.targets, control, visualization, artifacts/outputs, and run information. Objects are bound to an instance and generation, and are revoked at lifecycle end.
Native backend handles are excluded because they would bypass pause, reset, recording, authorization, and arbitration. Backend-specific behavior must appear through an explicit Provider capability or extension contract.
See Official plugins for the current packages.
From package installation to a scoped grant
A usable instance requires an installed distribution, readable Manifest entry point, a compatible Plugin ID selected by the Run, and valid bindings/access compiled for that instance. Only then does runtime import the selected factory, verify its descriptor, and create it.
The Manifest describes identity, role, compatibility, Scenario regions, services, and capabilities. The Factory is the installed construction entry point. The Instance is one Run-specific object with configuration, entity bindings, access, authority, and lifecycle. Those are distinct contracts.
Bindings answer “which entity?” while access answers “what may this instance do?” Scoped services are tied to the plugin and current generation; reset, stop, and close revoke them. A plugin must not store a service in a global singleton or keep submitting after close.
When Mission, Model, Teleop, Replay, or a remote source overlap, compiled control precedence governs admission and preemption. Plugins do not race to be the last writer. A release candidate should prove wheel-installed discovery, both entry points, descriptor compatibility, lifecycle cleanup, and only the real backend or hardware claims it advertises.