Crate meerkat_runtime

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 (Initializing ↔ Idle ↔ Attached ↔ Running ↔ Retired/Stopped/Destroyed)
Retire/recycle/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 accept::RejectReason;
pub use coalescing::AggregateDescriptor;
pub use coalescing::CoalescingResult;
pub use coalescing::SupersessionScope;
pub use coalescing::check_supersession;
pub use coalescing::create_aggregate_input;
pub use coalescing::is_coalescing_eligible;
pub use completion::CompletionCleanupObservation;
pub use completion::CompletionHandle;
pub use completion::CompletionOutcome;
pub use completion::CompletionWaitError;
pub use driver::EphemeralRuntimeDriver;
pub use driver::PersistentRuntimeDriver;
pub use driver::PostAdmissionSignal;
pub use handles::HandleDslAuthority;
pub use handles::RuntimeAuthLeaseHandle;
pub use handles::RuntimeCommsDrainHandle;
pub use handles::RuntimeExternalToolSurfaceHandle;
pub use handles::RuntimeInteractionStreamHandle;
pub use handles::RuntimeMcpServerLifecycleHandle;
pub use handles::RuntimeModelRoutingHandle;
pub use handles::RuntimePeerCommsHandle;
pub use handles::RuntimePeerInteractionHandle;
pub use handles::RuntimeSessionAdmissionHandle;
pub use handles::RuntimeSessionContextHandle;
pub use handles::RuntimeTurnStateHandle;
pub use identifiers::CausationId;
pub use identifiers::ConversationId;
pub use identifiers::CorrelationId;
pub use identifiers::EventCodeId;
pub use identifiers::IdempotencyKey;
pub use identifiers::InputKind;
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 ingress_types::ContentShape;
pub use ingress_types::RequestId;
pub use ingress_types::ReservationKey;
pub use input::ContinuationInput;
pub use input::ContinuationKind;
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::OperationInput;
pub use input::PeerConvention;
pub use input::PeerInput;
pub use input::PromptInput;
pub use input::ResponseProgressPhase;
pub use input::ResponseTerminalStatus;
pub use input::peer_response_terminal_input;
pub use input::response_terminal_status_from_wire;
pub use input_ledger::InputLedger;
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 meerkat_machine::CommsDrainMode;
pub use meerkat_machine::CommsDrainPhase;
pub use meerkat_machine::DrainExitReason;
pub use meerkat_machine::MachineSessionControlAuthority;
pub use meerkat_machine::MeerkatConsumerSurface;
pub use meerkat_machine::MeerkatMachine;
pub use meerkat_machine::PeerIngressOwner;
pub use meerkat_machine::RuntimeBindingsError;
pub use meerkat_machine::RuntimeLifecycleFacts;
pub use meerkat_machine::RuntimeLoopQueueAdmissionPlan;
pub use meerkat_machine::classify_runtime_lifecycle_state;
pub use meerkat_machine::classify_runtime_loop_queue_admission;
pub use meerkat_machine::standalone_tool_visibility_owner;
pub use ops_lifecycle::OpsLifecycleConfig;
pub use ops_lifecycle::OpsLifecyclePersistenceRequest;
pub use ops_lifecycle::PersistedOpsSnapshot;
pub use ops_lifecycle::RuntimeOpsLifecycleRegistry;
pub use interrupt_public_result::UserInterruptObservation;
pub use interrupt_public_result::UserInterruptPublicResult;
pub use interrupt_public_result::resolve_user_interrupt_public_result;
pub use peer_handling_mode::PeerHandlingModeError;
pub use peer_handling_mode::validate_peer_handling_mode;
pub use policy::ApplyMode;
pub use policy::ConsumePoint;
pub use policy::DrainPolicy;
pub use policy::PolicyDecision;
pub use policy::QueueMode;
pub use policy::RoutingDisposition;
pub use policy::WakeMode;
pub use policy_table::DefaultPolicyTable;
pub use policy_table::generated_default_policy_version;
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::SessionServiceRuntimeExt;
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::RecycleReport;
pub use traits::ResetReport;
pub use traits::RetireReport;
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.
auth_machine: AuthMachine runtime surface.
coalescing: §16 Coalescing — merging compatible inputs into aggregates.
comms_bridge: Runtime comms bridge helpers.
comms_drain: Comms inbox drain task.
comms_trust_reconcile: Comms trust reconciliation handler.
completion: Input completion waiters — allows callers to await terminal outcome of an accepted input.
composition: Composition dispatcher — THE typed execution path for routed effects.
driver: Runtime driver implementations.
handles: Runtime-side impls of the cross-crate DSL handle traits defined in meerkat_core::handles.
identifiers: §6 Runtime-layer identifiers.
ingress_types: Wire-type shells preserved from the deleted runtime ingress authority.
input: §8 Input types — the 6 input variants accepted by the runtime layer.
input_ledger: InputLedger — in-memory ledger of InputState entries.
input_scope: §11 InputScope — scoping for queue filtering and input targeting.
input_state: §13 InputState — per-input data shell.
interrupt_public_result
meerkat_machine: MeerkatMachine — session-scoped execution kernel.
mob_adapter: MobRuntimeAdapter — bridges mob provisioning to v9 RuntimeDriver lifecycle.
mob_operator_authority: Generated MeerkatMachine authority bridge for mob operator access.
ops_lifecycle: In-memory runtime implementation of the shared async-operation lifecycle seam.
peer_handling_mode: Peer handling-mode validation — reject handling_mode on response progress conventions.
policy: §12 PolicyDecision — generated admission-policy output.
policy_table: Generated admission-policy projection facade.
protocol_auth_lease_lifecycle_publication
protocol_auth_release_oauth_flow_drain
protocol_comms_trust_reconcile
protocol_supervisor_trust_publish
protocol_supervisor_trust_revoke
queue: InputQueue — FIFO queue with scope filtering.
runtime_event: §7 RuntimeEvent — full event hierarchy for runtime observability.
runtime_state: §22 RuntimeState — the runtime’s public state projection.
service_ext: SessionServiceRuntimeExt — v9 runtime extension for SessionService.
store: RuntimeStore — atomic persistence for runtime state.
traits: §23 Runtime traits — RuntimeDriver and RuntimeControlPlane.