Expand description
meerkat-runtime — v9 runtime control-plane for Meerkat agent lifecycle.
This crate implements the runtime/control-plane layer of the v9 Canonical
Lifecycle specification. It sits between surfaces (CLI, RPC, REST, MCP)
and core (meerkat-core), managing:
- Input acceptance, validation, and queueing
- InputState lifecycle tracking
- Policy resolution (what to do with each input)
- Runtime state machine (Idle ↔ Running ↔ Recovering → Stopped/Destroyed)
- Retire/respawn/reset lifecycle operations
- RuntimeEvent observability
Core-facing types (RunPrimitive, RunEvent, CoreExecutor, etc.) live in
meerkat-core::lifecycle. This crate contains everything else.
Re-exports§
pub use accept::AcceptOutcome;pub use coalescing::AggregateDescriptor;pub use coalescing::CoalescingResult;pub use coalescing::SupersessionScope;pub use coalescing::apply_coalescing;pub use coalescing::apply_supersession;pub use coalescing::check_supersession;pub use coalescing::create_aggregate_input;pub use coalescing::is_coalescing_eligible;pub use completion::CompletionHandle;pub use completion::CompletionOutcome;pub use completion::CompletionRegistry;pub use driver::EphemeralRuntimeDriver;pub use driver::PersistentRuntimeDriver;pub use durability::DurabilityError;pub use durability::validate_durability;pub use identifiers::CausationId;pub use identifiers::ConversationId;pub use identifiers::CorrelationId;pub use identifiers::EventCodeId;pub use identifiers::IdempotencyKey;pub use identifiers::KindId;pub use identifiers::LogicalRuntimeId;pub use identifiers::PolicyVersion;pub use identifiers::ProjectionRuleId;pub use identifiers::RuntimeEventId;pub use identifiers::SchemaId;pub use identifiers::SupersessionKey;pub use input::ExternalEventInput;pub use input::FlowStepInput;pub use input::Input;pub use input::InputDurability;pub use input::InputHeader;pub use input::InputOrigin;pub use input::InputVisibility;pub use input::PeerConvention;pub use input::PeerInput;pub use input::ProjectedInput;pub use input::PromptInput;pub use input::ResponseProgressPhase;pub use input::ResponseTerminalStatus;pub use input::SystemGeneratedInput;pub use input_ledger::InputLedger;pub use input_machine::InputStateMachine;pub use input_machine::InputStateMachineError;pub use input_scope::InputScope;pub use input_state::InputAbandonReason;pub use input_state::InputLifecycleState;pub use input_state::InputState;pub use input_state::InputStateEvent;pub use input_state::InputStateHistoryEntry;pub use input_state::InputTerminalOutcome;pub use input_state::PolicySnapshot;pub use input_state::ReconstructionSource;pub use lifecycle_ops::abandon_non_terminal;pub use lifecycle_ops::would_abandon;pub use policy::ApplyMode;pub use policy::ConsumePoint;pub use policy::PolicyDecision;pub use policy::QueueMode;pub use policy::WakeMode;pub use policy_table::DEFAULT_POLICY_VERSION;pub use policy_table::DefaultPolicyTable;pub use queue::InputQueue;pub use runtime_event::InputLifecycleEvent;pub use runtime_event::RunLifecycleEvent;pub use runtime_event::RuntimeEvent;pub use runtime_event::RuntimeEventEnvelope;pub use runtime_event::RuntimeProjectionEvent;pub use runtime_event::RuntimeStateChangeEvent;pub use runtime_event::RuntimeTopologyEvent;pub use runtime_state::RuntimeState;pub use runtime_state::RuntimeStateTransitionError;pub use service_ext::RuntimeMode;pub use service_ext::SessionServiceRuntimeExt;pub use session_adapter::RuntimeSessionAdapter;pub use state_machine::RuntimeStateMachine;pub use store::InMemoryRuntimeStore;pub use store::RuntimeStore;pub use store::RuntimeStoreError;pub use store::SessionDelta;pub use traits::DestroyReport;pub use traits::RecoveryReport;pub use traits::ResetReport;pub use traits::RespawnReport;pub use traits::RetireReport;pub use traits::RuntimeControlCommand;pub use traits::RuntimeControlPlane;pub use traits::RuntimeControlPlaneError;pub use traits::RuntimeDriver;pub use traits::RuntimeDriverError;pub use ::tokio;
Modules§
- accept
- §14 AcceptOutcome — result of accepting an input.
- coalescing
- §16 Coalescing — merging compatible inputs into aggregates.
- comms_
bridge - CommsInputBridge — translates InboxInteraction → v9 Input::PeerInput.
- comms_
sink - Concrete RuntimeInputSink implementation.
- completion
- Input completion waiters — allows callers to await terminal outcome of an accepted input.
- driver
- Runtime driver implementations.
- durability
- §10 Durability validation — enforce durability rules on inputs.
- identifiers
- §6 Runtime-layer identifiers.
- input
- §8 Input types — the 6 input variants accepted by the runtime layer.
- input_
ledger - InputLedger — in-memory ledger of InputState entries.
- input_
machine - §15 InputStateMachine — enforces all mandatory lifecycle transitions.
- input_
scope - §11 InputScope — scoping for queue filtering and input targeting.
- input_
state - §13 InputState — the lifecycle state machine for inputs.
- lifecycle_
ops - §25 Lifecycle operations — retire, respawn, reset, destroy.
- mob_
adapter - MobRuntimeAdapter — bridges mob provisioning to v9 RuntimeDriver lifecycle.
- policy
- §12 PolicyDecision — the output of the policy table.
- policy_
table - §17 DefaultPolicyTable — resolves Input × runtime_idle to PolicyDecision.
- queue
- InputQueue — FIFO queue with scope filtering.
- runtime_
event - §7 RuntimeEvent — full event hierarchy for runtime observability.
- runtime_
state - §22 RuntimeState — the runtime’s own state machine with validated transitions.
- service_
ext - SessionServiceRuntimeExt — v9 runtime extension for SessionService.
- session_
adapter - RuntimeSessionAdapter — wraps a SessionService with per-session RuntimeDrivers.
- state_
machine - Concrete RuntimeStateMachine — wraps RuntimeState with RunId tracking.
- store
- RuntimeStore — atomic persistence for runtime state.
- traits
- §23 Runtime traits — RuntimeDriver and RuntimeControlPlane.