meerkat_mob/
lib.rs

1//! Meerkat Mob - Multi-agent orchestration runtime.
2//!
3//! This crate provides the runtime for orchestrating multiple Meerkat agents
4//! (meerkats) as a collaborative mob. It handles spawning, wiring, lifecycle
5//! management, and shared task coordination.
6//!
7//! # Architecture
8//!
9//! `meerkat-mob` is a plugin crate with a one-way dependency on the Meerkat
10//! platform. No core Meerkat crate depends on this crate.
11//!
12//! Key types:
13//! - [`MobDefinition`] - Describes mob structure (profiles, wiring, skills)
14//! - [`MobEvent`] / [`MobEventKind`] - Structural state changes
15//! - [`Roster`] - Projected view of active meerkats
16//! - [`TaskBoard`] - Projected view of shared tasks
17//! - [`MobEventStore`] - Persistence trait for mob events
18//! - [`MobStorage`] - Storage bundle for a mob
19#![cfg_attr(
20    test,
21    allow(
22        clippy::unwrap_used,
23        clippy::expect_used,
24        clippy::panic,
25        clippy::redundant_clone,
26        clippy::io_other_error,
27        clippy::collapsible_if,
28        clippy::await_holding_lock
29    )
30)]
31
32// On wasm32, use tokio_with_wasm as a drop-in replacement for tokio.
33#[cfg(target_arch = "wasm32")]
34pub mod tokio {
35    pub use tokio_with_wasm::alias::*;
36}
37
38pub mod backend;
39pub mod build;
40pub mod definition;
41pub mod error;
42pub mod event;
43mod generated;
44pub mod ids;
45pub mod launch;
46pub mod profile;
47pub mod roster;
48pub mod run;
49pub mod runtime;
50pub mod runtime_mode;
51pub mod snapshot;
52pub mod spec;
53pub mod storage;
54pub mod store;
55pub mod tasks;
56pub mod validate;
57
58// Re-exports for convenience
59pub use backend::{MobBackendKind, RuntimeBinding};
60pub use definition::MobDefinition;
61pub use error::MobError;
62pub use event::{AttributedEvent, MemberRef, MobEvent, MobEventKind, NewMobEvent};
63pub use ids::{
64    BranchId, FlowId, FlowNodeId, FrameId, LoopId, LoopInstanceId, MeerkatId, MobId, ProfileName,
65    RunId, StepId, TaskId,
66};
67pub use launch::{BudgetSplitPolicy, ForkContext, MemberLaunchMode};
68pub use profile::{Profile, ProfileBinding, ProfileSource, SpawnTooling, ToolConfig};
69pub use roster::{
70    MemberState, MobMemberKickoffPhase, MobMemberKickoffSnapshot, Roster, RosterAddEntry,
71    RosterEntry,
72};
73pub use run::{
74    FailureLedgerEntry, FlowContext, FlowRunConfig, FrameSnapshot, LoopContextHistory,
75    LoopIterationLedgerEntry, LoopSnapshot, MobRun, MobRunStatus, StepLedgerEntry, StepRunStatus,
76};
77pub use runtime::RestoreIncompatible;
78pub use runtime::{FlowFrameKernel, FlowFrameMutator};
79pub use runtime::{FlowTurnExecutor, FlowTurnOutcome, FlowTurnTicket, TimeoutDisposition};
80pub use runtime::{
81    HelperOptions, HelperResult, MemberDeliveryReceipt, MemberHandle, MemberRespawnReceipt,
82    MemberSessionRef, MobBuilder, MobEventRouterConfig, MobEventRouterHandle, MobHandle,
83    MobMemberSnapshot, MobMemberStatus, MobPeerConnectivitySnapshot, MobRespawnError,
84    MobSessionService, MobState, MobUnreachablePeer, PeerTarget, SpawnMemberSpec, SpawnPolicy,
85    SpawnSpec,
86};
87pub use runtime::{SchedulerGrant, pump_schedulers_to_exhaustion};
88pub use runtime_mode::MobRuntimeMode;
89pub use snapshot::ParentToolScopeSnapshot;
90pub use spec::SpecValidator;
91pub use storage::MobStorage;
92pub use store::{
93    InMemoryMobEventStore, InMemoryMobRunStore, InMemoryMobSpecStore, InMemoryRealmProfileStore,
94    MobEventStore, MobRunStore, MobSpecStore, MobStoreError, RealmProfileStore, StoredRealmProfile,
95};
96#[cfg(not(target_arch = "wasm32"))]
97pub use store::{
98    SqliteMobEventStore, SqliteMobRunStore, SqliteMobSpecStore, SqliteMobStores,
99    SqliteRealmProfileStore,
100};
101pub use tasks::{MobTask, TaskBoard, TaskStatus};
102pub use validate::{
103    Diagnostic, DiagnosticCode, DiagnosticSeverity, partition_diagnostics, validate_definition,
104};
105
106/// Closure called at each member spawn to get a fresh snapshot of external tools.
107///
108/// Returns `None` when no external tools are registered yet (e.g. before SDK
109/// has called `tools/register`). The mob layer calls this lazily per-spawn so
110/// tools registered after mob creation are picked up.
111pub type ExternalToolsProvider = std::sync::Arc<
112    dyn Fn() -> Option<std::sync::Arc<dyn meerkat_core::agent::AgentToolDispatcher>> + Send + Sync,
113>;
114
115#[cfg(test)]
116mod tests;
meerkat_mob/lib.rs

meerkat_mob/
lib.rs
