meerkat_runtime/
lib.rs

1//! meerkat-runtime — v9 runtime control-plane for Meerkat agent lifecycle.
2//!
3//! This crate implements the runtime/control-plane layer of the v9 Canonical
4//! Lifecycle specification. It sits between surfaces (CLI, RPC, REST, MCP)
5//! and core (`meerkat-core`), managing:
6//!
7//! - Input acceptance, validation, and queueing
8//! - InputState lifecycle tracking
9//! - Policy resolution (what to do with each input)
10//! - Runtime state machine (Initializing ↔ Idle ↔ Attached ↔ Running ↔ Retired/Stopped/Destroyed)
11//! - Retire/recycle/reset lifecycle operations
12//! - RuntimeEvent observability
13//!
14//! Core-facing types (RunPrimitive, RunEvent, CoreExecutor, etc.) live in
15//! `meerkat-core::lifecycle`. This crate contains everything else.
16
17#![cfg_attr(
18    test,
19    allow(
20        dead_code,
21        unused_imports,
22        clippy::expect_used,
23        clippy::large_futures,
24        clippy::needless_borrow,
25        clippy::panic,
26        clippy::redundant_closure_for_method_calls,
27        clippy::redundant_clone,
28        clippy::type_complexity,
29        clippy::unnecessary_to_owned,
30        clippy::unwrap_used
31    )
32)]
33
34#[cfg(target_arch = "wasm32")]
35pub mod tokio {
36    pub use tokio_with_wasm::alias::*;
37}
38
39#[cfg(not(target_arch = "wasm32"))]
40pub use ::tokio;
41
42pub mod accept;
43pub mod auth_machine;
44pub mod coalescing;
45pub mod comms_bridge;
46pub mod comms_drain;
47pub mod comms_trust_reconcile;
48pub mod completion;
49pub mod composition;
50pub(crate) mod control_plane;
51pub mod driver;
52pub mod durability;
53pub(crate) mod effect;
54#[doc(hidden)]
55pub mod generated;
56pub mod handles;
57pub mod identifiers;
58pub mod ingress_types;
59pub mod input;
60pub mod input_ledger;
61pub mod input_scope;
62pub mod input_state;
63pub mod meerkat_machine;
64pub(crate) mod meerkat_machine_types;
65pub mod mob_adapter;
66pub mod ops_lifecycle;
67pub mod peer_handling_mode;
68pub mod policy;
69pub mod policy_table;
70#[allow(unused_imports)]
71#[path = "generated/protocol_supervisor_trust_publish.rs"]
72pub mod protocol_supervisor_trust_publish;
73pub mod queue;
74pub mod runtime_event;
75pub(crate) mod runtime_loop;
76pub mod runtime_state;
77pub mod service_ext;
78pub mod silent_intent;
79pub mod store;
80pub mod traits;
81
82use meerkat_core::lifecycle::run_primitive::RuntimeTurnMetadata as RuntimeStampedTurnMetadata;
83use std::any::Any;
84use std::sync::Arc;
85
86struct SessionRuntimeBindingsAuthority;
87
88pub(crate) fn session_runtime_bindings_authority() -> Arc<dyn Any + Send + Sync> {
89    Arc::new(SessionRuntimeBindingsAuthority)
90}
91
92pub(crate) fn local_session_runtime_bindings_authority() -> Arc<dyn Any + Send + Sync> {
93    session_runtime_bindings_authority()
94}
95
96pub fn session_runtime_bindings_have_machine_authority(
97    bindings: &meerkat_core::SessionRuntimeBindings,
98) -> bool {
99    bindings
100        .__runtime_authority()
101        .is::<SessionRuntimeBindingsAuthority>()
102}
103
104// Re-exports for convenience
105pub use accept::{AcceptOutcome, RejectReason, post_admission_signal_from_accept_outcome};
106pub use coalescing::{
107    AggregateDescriptor, CoalescingResult, SupersessionScope, apply_coalescing, apply_supersession,
108    check_supersession, create_aggregate_input, is_coalescing_eligible,
109};
110pub use completion::{CompletionHandle, CompletionOutcome};
111pub use driver::{EphemeralRuntimeDriver, PersistentRuntimeDriver, PostAdmissionSignal};
112pub use durability::{DurabilityError, validate_durability};
113pub use handles::{
114    HandleDslAuthority, RuntimeAuthLeaseHandle, RuntimeCommsDrainHandle,
115    RuntimeExternalToolSurfaceHandle, RuntimeInteractionStreamHandle,
116    RuntimeMcpServerLifecycleHandle, RuntimeModelRoutingHandle, RuntimePeerCommsHandle,
117    RuntimePeerInteractionHandle, RuntimeSessionAdmissionHandle, RuntimeSessionContextHandle,
118    RuntimeTurnStateHandle,
119};
120pub use identifiers::{
121    CausationId, ConversationId, CorrelationId, EventCodeId, IdempotencyKey, InputKind, KindId,
122    LogicalRuntimeId, PolicyVersion, ProjectionRuleId, RuntimeEventId, SchemaId, SupersessionKey,
123};
124pub use ingress_types::{ContentShape, RequestId, ReservationKey};
125pub use input::{
126    ContinuationInput, ExternalEventInput, FlowStepInput, Input, InputDurability, InputHeader,
127    InputOrigin, InputVisibility, OperationInput, PeerConvention, PeerInput, PromptInput,
128    ResponseProgressPhase, ResponseTerminalStatus, peer_response_terminal_input,
129    response_terminal_status_from_wire,
130};
131pub use input_ledger::InputLedger;
132pub use input_scope::InputScope;
133pub use input_state::{
134    InputAbandonReason, InputLifecycleState, InputState, InputStateEvent, InputStateHistoryEntry,
135    InputTerminalOutcome, MAX_STAGE_ATTEMPTS, PolicySnapshot, ReconstructionSource,
136};
137pub use meerkat_core::types::HandlingMode;
138pub use meerkat_machine::{
139    CommsDrainMode, CommsDrainPhase, DrainExitReason, MachineSessionControlAuthority,
140    MeerkatConsumerSurface, MeerkatMachine, PeerIngressOwner, RuntimeBindingsError,
141};
142pub use meerkat_machine_types::{
143    HydratedSessionLlmState, ImageOperationRoutingRequest, ImageOperationRoutingResult,
144    ModelRoutingApprovalDisposition, ModelRoutingRealtimePolicy, ResolvedSessionLlmReconfigure,
145    SessionLlmCapabilitySurface, SessionLlmCapabilitySurfaceStatus, SessionLlmReconfigureHost,
146    SessionLlmReconfigureReport, SessionLlmReconfigureRequest, SessionToolVisibilityDelta,
147};
148#[doc(hidden)]
149pub use meerkat_machine_types::{
150    MeerkatAdmittedInputSnapshot, MeerkatBindingSnapshot, MeerkatCompletionWaiterSnapshot,
151    MeerkatCompletionWaitersSnapshot, MeerkatControlSnapshot, MeerkatCursorSnapshot,
152    MeerkatDrainSnapshot, MeerkatDriverKind, MeerkatInputsSnapshot, MeerkatMachineCatalogInput,
153    MeerkatMachineCommandClassification, MeerkatMachineCommandClassificationRecord,
154    MeerkatMachineCommandVariant, MeerkatMachineFieldlessRuntimeInternalInput,
155    MeerkatMachineRuntimeInternalClassificationRecord, MeerkatMachineRuntimeInternalInput,
156    MeerkatMachineRuntimeInternalReason, MeerkatMachineShellMechanicReason,
157    MeerkatMachineSpineSnapshot, MeerkatOpsSnapshot,
158    canonical_meerkat_machine_command_classifications,
159    canonical_meerkat_machine_command_input_variant_manifest,
160    canonical_meerkat_machine_command_manifest,
161    canonical_meerkat_machine_runtime_internal_classifications,
162    canonical_meerkat_machine_runtime_internal_fieldless_input_variant_manifest,
163    canonical_meerkat_machine_runtime_internal_input_variant_manifest,
164    canonical_meerkat_machine_runtime_internal_manifest,
165};
166pub use ops_lifecycle::{
167    OpsLifecycleConfig, OpsLifecyclePersistenceRequest, PersistedOpsSnapshot,
168    RuntimeOpsLifecycleRegistry,
169};
170
171/// Stamp prompt turn metadata with the runtime-owned input semantics.
172///
173/// This helper exists for runtime-backed service-turn paths that already hold
174/// machine admission and must pass a runtime-classified prompt turn into the
175/// session layer. New prompt materialization should prefer `MeerkatMachine`
176/// input admission so the machine creates this metadata directly.
177pub fn runtime_stamped_prompt_turn_metadata(
178    metadata: Option<RuntimeStampedTurnMetadata>,
179) -> RuntimeStampedTurnMetadata {
180    let input = Input::Prompt(PromptInput::from_content_input(
181        meerkat_core::ContentInput::Text(String::new()),
182        metadata,
183    ));
184    let policy = policy_table::DefaultPolicyTable::resolve(&input, true);
185    let semantics =
186        ingress_types::RuntimeInputSemantics::from_policy_and_kind(&policy, input.kind());
187    runtime_loop::for_input(&input, semantics)
188}
189
190#[doc(hidden)]
191pub mod machine_schema_exports {
192    pub fn meerkat_machine_schema() -> meerkat_machine_schema::MachineSchema {
193        meerkat_machine_schema::catalog::dsl::meerkat_machine_schema_metadata()
194            .attach_to(crate::meerkat_machine::dsl::MeerkatMachineState::schema())
195    }
196
197    pub fn auth_machine_schema() -> meerkat_machine_schema::MachineSchema {
198        meerkat_machine_schema::catalog::dsl::auth_machine_schema_metadata()
199            .attach_to(crate::auth_machine::dsl::AuthMachineState::schema())
200    }
201}
202pub use peer_handling_mode::{PeerHandlingModeError, validate_peer_handling_mode};
203pub use policy::{
204    ApplyMode, ConsumePoint, DrainPolicy, PolicyDecision, QueueMode, RoutingDisposition, WakeMode,
205};
206pub use policy_table::{DEFAULT_POLICY_VERSION, DefaultPolicyTable};
207pub use queue::InputQueue;
208pub use runtime_event::{
209    InputLifecycleEvent, RunLifecycleEvent, RuntimeEvent, RuntimeEventEnvelope,
210    RuntimeProjectionEvent, RuntimeStateChangeEvent, RuntimeTopologyEvent,
211};
212pub use runtime_state::{RuntimeState, RuntimeStateTransitionError};
213pub use service_ext::{RuntimeMode, SessionServiceRuntimeExt};
214pub use store::{InMemoryRuntimeStore, RuntimeStore, RuntimeStoreError, SessionDelta};
215pub use traits::{
216    DestroyReport, RecoveryReport, RecycleReport, ResetReport, RetireReport, RuntimeControlPlane,
217    RuntimeControlPlaneError, RuntimeDriver, RuntimeDriverError,
218};
meerkat_runtime/lib.rs

meerkat_runtime/
lib.rs
