meerkat-mob 0.7.0

//! Meerkat Mob - Multi-agent orchestration runtime.
//!
//! This crate provides the runtime for orchestrating multiple agents as a
//! collaborative mob. It handles member 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
//! - [`MobEventStore`] - Persistence trait for mob events
//! - [`MobStorage`] - Storage bundle for a mob
#![allow(
    dead_code,
    unused_imports,
    unused_variables,
    clippy::collapsible_if,
    clippy::expect_used,
    clippy::if_not_else,
    clippy::implicit_clone,
    clippy::large_futures,
    clippy::redundant_closure_for_method_calls,
    clippy::redundant_clone,
    clippy::redundant_feature_names,
    clippy::unnecessary_to_owned
)]
#![cfg_attr(
    test,
    allow(
        clippy::unwrap_used,
        clippy::panic,
        clippy::io_other_error,
        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;
mod build;
pub mod coordination;
pub mod definition;
pub mod error;
pub mod event;
#[doc(hidden)]
pub mod generated;
pub mod ids;
pub mod launch;
#[doc(hidden)]
pub mod machines;
mod mob_machine;
pub mod profile;
mod roster;
pub mod run;
pub mod runtime;
pub mod runtime_mode;
mod snapshot;
pub mod spec;
pub mod storage;
pub mod store;
pub mod validate;
pub mod workgraph_attention;

// Re-exports for convenience
pub use backend::{MobBackendKind, RuntimeBinding};
pub use coordination::{
    CoordinationOwner, CoordinationRecordRefs, CoordinationResourceRef, MobCoordinationError,
    MobCoordinationEvent, MobCoordinationEventKind, MobCoordinationSnapshot, ResourceClaim,
    ResourceClaimId, ResourceClaimKind, ResourceClaimStatus, WorkIntent, WorkIntentId,
    WorkIntentStatus,
};
pub use definition::MobDefinition;
pub use error::{MobError, MobFailureClass};
pub use event::{AttributedEvent, MemberWireEdge, MobEvent, MobEventKind, NewMobEvent};
pub use ids::{
    AgentIdentity, AgentRuntimeId, BranchId, FenceToken, FlowId, FlowNodeId, FrameId, Generation,
    LoopId, LoopInstanceId, MobId, ProfileName, RespawnTopologyPeerId, RunId, StepId, WorkOrigin,
    WorkRef, WorkSpec,
};
pub use launch::{BudgetSplitPolicy, ForkContext, MemberLaunchMode};
#[doc(hidden)]
pub use mob_machine::{
    MobMachineCatalogInput, MobMachineCommandClassification, MobMachineCommandClassificationRecord,
    MobMachineCommandVariant, MobMachineRuntimeInternalClassificationRecord,
    MobMachineRuntimeInternalReason, MobMachineShellMechanicReason,
    canonical_mob_machine_command_classifications,
    canonical_mob_machine_command_input_variant_manifest, canonical_mob_machine_command_manifest,
    canonical_mob_machine_runtime_internal_classifications,
    canonical_mob_machine_runtime_internal_input_variant_manifest,
    canonical_mob_machine_runtime_internal_manifest,
};
pub use workgraph_attention::{
    lower_agent_identity_attention_target, lower_agent_identity_owner_key,
};

#[doc(hidden)]
pub mod machine_schema_exports {
    pub fn mob_machine_schema() -> meerkat_machine_schema::MachineSchema {
        meerkat_machine_schema::catalog::dsl::mob_machine_schema_metadata()
            .attach_to(crate::machines::mob_machine::MobMachineState::schema())
    }
}

pub use profile::{
    Profile, ProfileBinding, ProfileSource, ResumeOverrideField, SpawnTooling, ToolConfig,
};
pub use roster::{MobMemberKickoffPhase, MobMemberKickoffSnapshot};
pub use run::{
    CreateMobAdmission, FailureLedgerEntry, FlowContext, FlowRunConfig, FrameSnapshot,
    LoopContextHistory, LoopIterationLedgerEntry, LoopSnapshot, MobFlowRunPublicResultClass,
    MobRun, MobRunStatus, ProfileMutationAdmission, StepLedgerEntry, StepRunStatus,
    mob_machine_create_mob_admission, mob_machine_profile_mutation_admission,
    mob_machine_run_public_result_class, mob_machine_run_status_is_terminal,
    mob_machine_step_status_is_terminal,
};
pub use runtime::RestoreIncompatible;
pub use runtime::bridge::{MobBoundMemberRuntimeBridge, MobMemberRuntimeBridge};
pub use runtime::bridge_protocol::{
    BridgeAck, BridgeBindPayload, BridgeBindResponse, BridgeCapabilities, BridgeCommand,
    BridgeDeliveryOutcome, BridgeDeliveryPayload, BridgeDeliveryRejectionCause,
    BridgeDeliveryResponse, BridgeDestroyResponse, BridgeHardCancelPayload,
    BridgeMemberRuntimeState, BridgeMobPeerOverlayHandoff, BridgeObservationResponse,
    BridgePeerConnectivity, BridgePeerSpec, BridgePeerWiringPayload, BridgeReply,
    BridgeRetireResponse, BridgeSupervisorPayload,
};
#[cfg(feature = "runtime-adapter")]
pub use runtime::local_bridge::LocalMobRuntimeBridge;
pub use runtime::{
    CurrentMobAdmission, ExternalPeerBindingSpec, HelperOptions, HelperResult,
    MemberDeliveryReceipt, MemberHandle, MemberRespawnReceipt, MobBuilder, MobDestroyError,
    MobDestroyReport, MobEventRouterConfig, MobEventRouterHandle, MobEventsSubscription,
    MobEventsSubscriptionConfig, MobHandle, MobMemberSnapshot, MobMemberStatus,
    MobPeerConnectivitySnapshot, MobRespawnError, MobSessionService, MobSpawnManyFailure, MobState,
    MobUnreachablePeer, MobWireMembersBatchReport, PeerMessageReceipt, PeerTarget,
    PreviousMemberCleanupReport, SpawnContinuityIntent, SpawnCustomizationContext,
    SpawnMemberAdmission, SpawnMemberAdmissionObservations, SpawnMemberCustomizer, SpawnMemberSpec,
    SpawnPolicy, SpawnResult, SpawnSource, SpawnSpec, SpawnSystemPromptOverride,
    SpawnToolAdmission, SupervisorRotationReport, WorkDeliveryReceipt, mob_error_wire_code,
    profile_to_wire, stored_realm_profile_to_wire,
};
pub use runtime::{FlowFrameKernel, FlowFrameMutator};
pub use runtime::{FlowTurnExecutor, FlowTurnOutcome, FlowTurnTicket, TimeoutDisposition};
pub use runtime_mode::MobRuntimeMode;
pub use spec::SpecValidator;
pub use storage::MobStorage;
pub use store::{
    ExternalBindingOverlayRecord, ExternalBindingOverlayStatus, InMemoryMobEventStore,
    InMemoryMobRunStore, InMemoryMobRuntimeMetadataStore, InMemoryMobSpecStore,
    InMemoryRealmProfileStore, MobEventReceiver, MobEventStore, MobRunStore,
    MobRuntimeMetadataStore, MobSpecStore, MobStoreError, RealmProfileStore, StoredRealmProfile,
    SupervisorAuthorityRecord,
};
#[cfg(not(target_arch = "wasm32"))]
pub use store::{
    SqliteMobEventStore, SqliteMobRunStore, SqliteMobRuntimeMetadataStore, SqliteMobSpecStore,
    SqliteMobStores, SqliteRealmProfileStore,
};
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;