Struct MobHandle 

pub struct MobHandle { /* private fields */ }

Clone-cheap, thread-safe handle for interacting with a running mob.

All mutation commands are sent through an mpsc channel to the actor. Read-only operations (roster, state) bypass the actor and read from shared Arc state directly.

Implementations

impl MobHandle

pub async fn poll_events( &self, after_cursor: u64, limit: usize, ) -> Result<Vec<MobEvent>, MobError>

Poll mob events from the underlying store.

pub fn status(&self) -> MobState

Current mob lifecycle state (lock-free read).

pub fn definition(&self) -> &MobDefinition

Access the mob definition.

pub fn mob_id(&self) -> &MobId

Mob ID.

pub async fn roster(&self) -> Roster

Snapshot of the current roster.

pub async fn list_members(&self) -> Vec<MobMemberListEntry>

List members as an operational projection surface.

This includes structural roster fields plus current runtime status, error/finality state, and the current session binding when known. It intentionally skips live peer-connectivity fanout so ordinary membership polling cannot stall on comms reachability lookups. For low-level structural roster visibility without runtime projection, use list_all_members.

pub async fn list_members_including_retiring(&self) -> Vec<MobMemberListEntry>

List all members including those in Retiring state, with canonical lifecycle/session projection.

Like list_members, this intentionally avoids live peer-connectivity fanout. Use member_status for deep per-member inspection including live comms reachability.

pub async fn list_all_members(&self) -> Vec<RosterEntry>

List all members including those in Retiring state.

The state field on each RosterEntry distinguishes Active from Retiring. Use this for observability and membership inspection where in-flight retires should be visible.

pub async fn get_member(&self, meerkat_id: &MeerkatId) -> Option<RosterEntry>

Get a specific member entry.

pub async fn member( &self, meerkat_id: &MeerkatId, ) -> Result<MemberHandle, MobError>

Acquire a capability-bearing handle for a specific active member.

pub fn events(&self) -> MobEventsView

Access a read-only events view for polling/replay.

pub async fn record_operator_action_provenance( &self, tool_name: &str, authority_context: &MobToolAuthorityContext, ) -> Result<(), MobError>

Append a dispatcher-owned operator provenance projection.

This is audit/projection data only. It must never become authorization truth.

pub async fn subscribe_agent_events( &self, meerkat_id: &MeerkatId, ) -> Result<EventStream, MobError>

Subscribe to agent-level events for a specific meerkat.

Looks up the meerkat’s session ID from the roster, then subscribes to the session-level event stream via MobSessionService.

Returns MobError::MeerkatNotFound if the meerkat is not in the roster or has no session ID.

pub async fn subscribe_all_agent_events(&self) -> Vec<(MeerkatId, EventStream)>

Subscribe to agent events for all active members (point-in-time snapshot).

Returns one stream per active member that has a session ID. Members spawned after this call are not included — use [subscribe_mob_events] for a continuously updated view.

pub fn subscribe_mob_events(&self) -> MobEventRouterHandle

Subscribe to a continuously-updated, mob-level event bus.

Spawns an independent task that merges per-member session streams, tags each event with [AttributedEvent], and tracks roster changes (spawns/retires) automatically. Drop the returned handle to stop the router.

pub fn subscribe_mob_events_with_config( &self, config: MobEventRouterConfig, ) -> MobEventRouterHandle

Like subscribe_mob_events with explicit config.

pub async fn mcp_server_states(&self) -> BTreeMap<String, bool>

Snapshot of MCP server lifecycle state tracked by this runtime.

pub async fn run_flow( &self, flow_id: FlowId, params: Value, ) -> Result<RunId, MobError>

Start a flow run and return its run ID.

pub async fn run_flow_with_stream( &self, flow_id: FlowId, params: Value, scoped_event_tx: Option<Sender<ScopedAgentEvent>>, ) -> Result<RunId, MobError>

Start a flow run with an optional scoped stream sink.

pub async fn cancel_flow(&self, run_id: RunId) -> Result<(), MobError>

Request cancellation of an in-flight flow run.

pub async fn flow_status( &self, run_id: RunId, ) -> Result<Option<MobRun>, MobError>

Fetch a flow run snapshot from the run store.

pub fn list_flows(&self) -> Vec<FlowId>

List all configured flow IDs in this mob definition.

pub async fn spawn( &self, profile_name: ProfileName, meerkat_id: MeerkatId, initial_message: Option<ContentInput>, ) -> Result<MemberRef, MobError>

Spawn a new member from a profile and return its member reference.

pub async fn spawn_with_binding( &self, profile_name: ProfileName, meerkat_id: MeerkatId, initial_message: Option<ContentInput>, binding: RuntimeBinding, ) -> Result<MemberRef, MobError>

Spawn a new member with an explicit runtime binding.

pub async fn spawn_with_backend( &self, profile_name: ProfileName, meerkat_id: MeerkatId, initial_message: Option<ContentInput>, backend: Option<MobBackendKind>, ) -> Result<MemberRef, MobError>

Spawn a new member from a profile with explicit backend override.

pub async fn spawn_with_options( &self, profile_name: ProfileName, meerkat_id: MeerkatId, initial_message: Option<ContentInput>, runtime_mode: Option<MobRuntimeMode>, backend: Option<MobBackendKind>, ) -> Result<MemberRef, MobError>

Spawn a new member from a profile with explicit runtime mode/backend overrides.

pub async fn attach_existing_session( &self, profile_name: ProfileName, meerkat_id: MeerkatId, session_id: SessionId, runtime_mode: Option<MobRuntimeMode>, backend: Option<MobBackendKind>, ) -> Result<MemberRef, MobError>

Attach an existing session by reusing the mob spawn control-plane path.

pub async fn attach_existing_session_as_orchestrator( &self, profile_name: ProfileName, meerkat_id: MeerkatId, session_id: SessionId, ) -> Result<MemberRef, MobError>

Attach an existing session as the mob orchestrator.

pub async fn attach_existing_session_as_member( &self, profile_name: ProfileName, meerkat_id: MeerkatId, session_id: SessionId, ) -> Result<MemberRef, MobError>

Attach an existing session as a regular mob member.

pub async fn spawn_spec( &self, spec: SpawnMemberSpec, ) -> Result<MemberRef, MobError>

Spawn a member from a fully-specified SpawnMemberSpec.

pub async fn spawn_many( &self, specs: Vec<SpawnMemberSpec>, ) -> Vec<Result<MemberRef, MobError>>

Spawn multiple members in parallel.

Results preserve input order.

pub async fn retire(&self, meerkat_id: MeerkatId) -> Result<(), MobError>

Retire a member, archiving its session and removing trust.

pub async fn respawn( &self, meerkat_id: MeerkatId, initial_message: Option<ContentInput>, ) -> Result<MemberRespawnReceipt, MobRespawnError>

Retire a member and respawn with the same profile, labels, wiring, and mode.

This is a helper convenience over primitive mob behavior, not a machine-owned primitive. Returns a receipt on full success, or a structured error on failure. No rollback is attempted after retire.

pub async fn retire_all(&self) -> Result<(), MobError>

Retire all roster members concurrently in a single actor command.

pub async fn wire<T>(&self, local: MeerkatId, target: T) -> Result<(), MobError>

where T: Into<PeerTarget>,

Wire a local member to either another local member or an external peer.

pub async fn unwire<T>( &self, local: MeerkatId, target: T, ) -> Result<(), MobError>

where T: Into<PeerTarget>,

Unwire a local member from either another local member or an external peer.

pub async fn internal_turn( &self, meerkat_id: MeerkatId, message: impl Into<ContentInput>, ) -> Result<MemberDeliveryReceipt, MobError>

Compatibility wrapper for internal-turn submission.

Prefer MobHandle::member plus MemberHandle::internal_turn for the target 0.5 API shape.

pub async fn stop(&self) -> Result<(), MobError>

Transition Running -> Stopped. Mutation commands are rejected while stopped.

pub async fn resume(&self) -> Result<(), MobError>

Transition Stopped -> Running.

pub async fn complete(&self) -> Result<(), MobError>

Archive all members, emit MobCompleted, and transition to Completed.

pub async fn reset(&self) -> Result<(), MobError>

Wipe all runtime state and transition back to Running.

Like destroy() but keeps the actor alive and transitions to Running instead of Destroyed. The handle remains usable after reset.

pub async fn destroy(&self) -> Result<(), MobError>

Retire active members, clear persisted mob storage, and terminate the actor.

pub async fn task_create( &self, subject: String, description: String, blocked_by: Vec<TaskId>, ) -> Result<TaskId, MobError>

Create a task in the shared mob task board.

pub async fn task_update( &self, task_id: TaskId, status: TaskStatus, owner: Option<MeerkatId>, ) -> Result<(), MobError>

Update task status/owner in the shared mob task board.

pub async fn task_list(&self) -> Result<Vec<MobTask>, MobError>

List tasks from the in-memory task board projection.

pub async fn task_get( &self, task_id: &TaskId, ) -> Result<Option<MobTask>, MobError>

Get a task by ID from the in-memory task board projection.

pub async fn set_spawn_policy( &self, policy: Option<Arc<dyn SpawnPolicy>>, ) -> Result<(), MobError>

Set or clear the spawn policy for automatic member provisioning.

When set, external turns targeting an unknown meerkat ID will consult the policy before returning MeerkatNotFound.

pub async fn shutdown(&self) -> Result<(), MobError>

Shut down the actor. After this, no more commands are accepted.

pub async fn force_cancel_member( &self, meerkat_id: MeerkatId, ) -> Result<(), MobError>

Force-cancel a member’s in-flight turn via session interrupt.

Unlike retire, this does not archive the session or remove the member from the roster — it only cancels the current turn.

pub async fn member_status( &self, meerkat_id: &MeerkatId, ) -> Result<MobMemberSnapshot, MobError>

Get a point-in-time execution snapshot for a member.

This is the deep inspection surface. Unlike list projections, it resolves live peer connectivity when a comms runtime is available.

pub async fn wait_for_kickoff_complete( &self, timeout: Option<Duration>, ) -> Result<Vec<(MeerkatId, MobMemberSnapshot)>, MobError>

Wait until all autonomous members have been admitted to the runtime.

Autonomous members no longer run a separate kickoff turn — their initial prompt is injected through the runtime input path at spawn time. This method returns member snapshots immediately since admission is synchronous.

pub async fn wait_for_members_kickoff_complete( &self, ids: &[MeerkatId], timeout: Option<Duration>, ) -> Result<Vec<(MeerkatId, MobMemberSnapshot)>, MobError>

Wait until the given autonomous members have been admitted to the runtime.

See wait_for_kickoff_complete for details.

pub async fn wait_one( &self, meerkat_id: &MeerkatId, ) -> Result<MobMemberSnapshot, MobError>

Wait for a specific member to reach a terminal state, then return its snapshot.

Polls canonical member classification until terminal.

pub async fn wait_all( &self, meerkat_ids: &[MeerkatId], ) -> Result<Vec<MobMemberSnapshot>, MobError>

Wait for all specified members to reach terminal states.

pub async fn collect_completed(&self) -> Vec<(MeerkatId, MobMemberSnapshot)>

Collect snapshots for all members that have reached terminal states.

pub async fn spawn_helper( &self, meerkat_id: MeerkatId, task: impl Into<String>, options: HelperOptions, ) -> Result<HelperResult, MobError>

Spawn a fresh helper, wait for it to complete, retire it, and return its result.

Helpers are short-lived TurnDriven tasks by default. Their completion truth is the spawn/create boundary plus the canonical post-spawn member snapshot, not full member terminality in the mob lifecycle.

pub async fn fork_helper( &self, source_member_id: &MeerkatId, meerkat_id: MeerkatId, task: impl Into<String>, fork_context: ForkContext, options: HelperOptions, ) -> Result<HelperResult, MobError>

Fork from an existing member’s context, wait for completion, retire, and return.

Like spawn_helper but uses MemberLaunchMode::Fork to share conversation context with the source member.

Trait Implementations

impl Clone for MobHandle

fn clone(&self) -> MobHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.