meerkat-mob 0.5.2

Multi-agent orchestration runtime for Meerkat
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! Meerkat Mob - Multi-agent orchestration runtime.
//!
//! This crate provides the runtime for orchestrating multiple Meerkat agents
//! (meerkats) as a collaborative mob. It handles spawning, wiring, lifecycle
//! management, and shared task coordination.
//!
//! # Architecture
//!
//! `meerkat-mob` is a plugin crate with a one-way dependency on the Meerkat
//! platform. No core Meerkat crate depends on this crate.
//!
//! Key types:
//! - [`MobDefinition`] - Describes mob structure (profiles, wiring, skills)
//! - [`MobEvent`] / [`MobEventKind`] - Structural state changes
//! - [`Roster`] - Projected view of active meerkats
//! - [`TaskBoard`] - Projected view of shared tasks
//! - [`MobEventStore`] - Persistence trait for mob events
//! - [`MobStorage`] - Storage bundle for a mob
#![cfg_attr(
    test,
    allow(
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::redundant_clone,
        clippy::io_other_error,
        clippy::collapsible_if,
        clippy::await_holding_lock
    )
)]

// On wasm32, use tokio_with_wasm as a drop-in replacement for tokio.
#[cfg(target_arch = "wasm32")]
pub mod tokio {
    pub use tokio_with_wasm::alias::*;
}

pub mod backend;
pub mod build;
pub mod definition;
pub mod error;
pub mod event;
mod generated;
pub mod ids;
pub mod launch;
pub mod profile;
pub mod roster;
pub mod run;
pub mod runtime;
pub mod runtime_mode;
pub mod snapshot;
pub mod spec;
pub mod storage;
pub mod store;
pub mod tasks;
pub mod validate;

// Re-exports for convenience
pub use backend::{MobBackendKind, RuntimeBinding};
pub use definition::MobDefinition;
pub use error::MobError;
pub use event::{AttributedEvent, MemberRef, MobEvent, MobEventKind, NewMobEvent};
pub use ids::{
    BranchId, FlowId, FlowNodeId, FrameId, LoopId, LoopInstanceId, MeerkatId, MobId, ProfileName,
    RunId, StepId, TaskId,
};
pub use launch::{BudgetSplitPolicy, ForkContext, MemberLaunchMode};
pub use profile::{Profile, ProfileBinding, ProfileSource, SpawnTooling, ToolConfig};
pub use roster::{
    MemberState, MobMemberKickoffPhase, MobMemberKickoffSnapshot, Roster, RosterAddEntry,
    RosterEntry,
};
pub use run::{
    FailureLedgerEntry, FlowContext, FlowRunConfig, FrameSnapshot, LoopContextHistory,
    LoopIterationLedgerEntry, LoopSnapshot, MobRun, MobRunStatus, StepLedgerEntry, StepRunStatus,
};
pub use runtime::RestoreIncompatible;
pub use runtime::{FlowFrameKernel, FlowFrameMutator};
pub use runtime::{FlowTurnExecutor, FlowTurnOutcome, FlowTurnTicket, TimeoutDisposition};
pub use runtime::{
    HelperOptions, HelperResult, MemberDeliveryReceipt, MemberHandle, MemberRespawnReceipt,
    MemberSessionRef, MobBuilder, MobEventRouterConfig, MobEventRouterHandle, MobHandle,
    MobMemberSnapshot, MobMemberStatus, MobPeerConnectivitySnapshot, MobRespawnError,
    MobSessionService, MobState, MobUnreachablePeer, PeerTarget, SpawnMemberSpec, SpawnPolicy,
    SpawnSpec,
};
pub use runtime::{SchedulerGrant, pump_schedulers_to_exhaustion};
pub use runtime_mode::MobRuntimeMode;
pub use snapshot::ParentToolScopeSnapshot;
pub use spec::SpecValidator;
pub use storage::MobStorage;
pub use store::{
    InMemoryMobEventStore, InMemoryMobRunStore, InMemoryMobSpecStore, InMemoryRealmProfileStore,
    MobEventStore, MobRunStore, MobSpecStore, MobStoreError, RealmProfileStore, StoredRealmProfile,
};
#[cfg(not(target_arch = "wasm32"))]
pub use store::{
    SqliteMobEventStore, SqliteMobRunStore, SqliteMobSpecStore, SqliteMobStores,
    SqliteRealmProfileStore,
};
pub use tasks::{MobTask, TaskBoard, TaskStatus};
pub use validate::{
    Diagnostic, DiagnosticCode, DiagnosticSeverity, partition_diagnostics, validate_definition,
};

/// Closure called at each member spawn to get a fresh snapshot of external tools.
///
/// Returns `None` when no external tools are registered yet (e.g. before SDK
/// has called `tools/register`). The mob layer calls this lazily per-spawn so
/// tools registered after mob creation are picked up.
pub type ExternalToolsProvider = std::sync::Arc<
    dyn Fn() -> Option<std::sync::Arc<dyn meerkat_core::agent::AgentToolDispatcher>> + Send + Sync,
>;

#[cfg(test)]
mod tests;