meerkat-mob 0.4.1

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

use super::events::MobEventEmitter;
use super::handle::MobHandle;
use crate::error::MobError;
use crate::ids::{RunId, StepId};
use crate::run::FlowRunConfig;
#[cfg(target_arch = "wasm32")]
use crate::tokio;
use std::time::Duration;

const ESCALATION_TURN_TIMEOUT: Duration = Duration::from_secs(2);

pub struct Supervisor {
    handle: MobHandle,
    emitter: MobEventEmitter,
}

impl Supervisor {
    pub fn new(handle: MobHandle, emitter: MobEventEmitter) -> Self {
        Self { handle, emitter }
    }

    pub async fn escalate(
        &self,
        config: &FlowRunConfig,
        run_id: &RunId,
        step_id: &StepId,
        reason: &str,
    ) -> Result<(), MobError> {
        let supervisor_role = config
            .supervisor
            .as_ref()
            .ok_or_else(|| MobError::SupervisorEscalation("supervisor not configured".into()))?
            .role
            .clone();

        let escalation_target = self
            .handle
            .list_members()
            .await
            .into_iter()
            .find(|entry| entry.profile == supervisor_role)
            .ok_or_else(|| {
                MobError::SupervisorEscalation(format!(
                    "no active supervisor member for role '{supervisor_role}'"
                ))
            })?;

        tokio::time::timeout(
            ESCALATION_TURN_TIMEOUT,
            self.handle.internal_turn(
                escalation_target.meerkat_id.clone(),
                format!("Supervisor escalation for run '{run_id}', step '{step_id}': {reason}"),
            ),
        )
        .await
        .map_err(|_| {
            MobError::SupervisorEscalation(format!(
                "supervisor escalation timed out after {}ms",
                ESCALATION_TURN_TIMEOUT.as_millis()
            ))
        })??;

        self.emitter
            .supervisor_escalation(
                run_id.clone(),
                step_id.clone(),
                escalation_target.meerkat_id,
            )
            .await?;

        Ok(())
    }

    pub async fn force_reset(&self) -> Result<(), MobError> {
        let ids = self
            .handle
            .list_members()
            .await
            .into_iter()
            .map(|entry| entry.meerkat_id)
            .collect::<Vec<_>>();

        let mut failures = Vec::new();
        for id in ids {
            if let Err(error) = self.handle.retire(id.clone()).await {
                failures.push(format!("{id}: {error}"));
            }
        }

        if !failures.is_empty() {
            return Err(MobError::SupervisorEscalation(format!(
                "force_reset encountered {} retirement error(s): {}",
                failures.len(),
                failures.join("; ")
            )));
        }

        Ok(())
    }
}