@pheem49/mint 1.16.0 → 1.17.0

package/crates/mint-core/src/swarm/dossier.rs

@@ -0,0 +1,152 @@
+//! Shapes what flows back into the main agent's context: capped, labelled,
+//! and compact — a chatty sub-agent must not re-bloat the context that
+//! delegation exists to protect.
+use super::{AgentStatus, SwarmOutcome};
+
+/// Most characters of one agent's result that reach the main agent.
+pub const MAX_DOSSIER_CHARS: usize = 4_000;
+
+pub fn cap_dossier(text: &str) -> String {
+    crate::orchestration::truncate_for_context(text.trim(), MAX_DOSSIER_CHARS)
+}
+
+/// One-line preview (first non-empty line, bounded) for UI summaries.
+pub fn summary_preview(text: &str) -> String {
+    let line = text
+        .lines()
+        .map(str::trim)
+        .find(|l| !l.is_empty())
+        .unwrap_or("");
+    if line.chars().count() <= 160 {
+        line.to_string()
+    } else {
+        let mut s: String = line.chars().take(160).collect();
+        s.push_str("...");
+        s
+    }
+}
+
+/// `400ms`, `12s`, `1m 05s`.
+pub fn format_elapsed_ms(ms: u64) -> String {
+    if ms < 1_000 {
+        return format!("{ms}ms");
+    }
+    let secs = ms / 1_000;
+    if secs < 60 {
+        format!("{secs}s")
+    } else {
+        format!("{}m {:02}s", secs / 60, secs % 60)
+    }
+}
+
+pub fn format_outcome(outcome: &SwarmOutcome) -> String {
+    let steps = if outcome.steps == 1 {
+        "1 step".to_string()
+    } else {
+        format!("{} steps", outcome.steps)
+    };
+    format!(
+        "[Agent '{}' · {} · {} · {}]\n{}",
+        outcome.label,
+        outcome.status.as_str(),
+        format_elapsed_ms(outcome.elapsed_ms),
+        steps,
+        outcome.text
+    )
+}
+
+/// The single tool result handed to the main agent for a whole batch.
+pub fn format_batch_result(outcomes: &[SwarmOutcome]) -> String {
+    let count = |s: AgentStatus| outcomes.iter().filter(|o| o.status == s).count();
+    let mut text = format!(
+        "Dispatched {} agents: {} completed / {} failed / {} cancelled.",
+        outcomes.len(),
+        count(AgentStatus::Completed),
+        count(AgentStatus::Failed),
+        count(AgentStatus::Cancelled),
+    );
+    for outcome in outcomes {
+        text.push_str("\n\n");
+        text.push_str(&format_outcome(outcome));
+    }
+    text
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn outcome(label: &str, status: AgentStatus, ms: u64, steps: u32, text: &str) -> SwarmOutcome {
+        SwarmOutcome {
+            label: label.into(),
+            profile: "explorer".into(),
+            status,
+            elapsed_ms: ms,
+            steps,
+            text: text.into(),
+        }
+    }
+
+    #[test]
+    fn cap_dossier_trims_but_leaves_short_text_alone() {
+        assert_eq!(cap_dossier("  findings  \n"), "findings");
+    }
+
+    #[test]
+    fn cap_dossier_truncates_with_a_marker() {
+        let capped = cap_dossier(&"x".repeat(20_000));
+        assert!(capped.ends_with("... [truncated]"));
+        assert!(capped.chars().count() <= MAX_DOSSIER_CHARS + "... [truncated]".len());
+    }
+
+    #[test]
+    fn elapsed_formats_for_humans() {
+        assert_eq!(format_elapsed_ms(400), "400ms");
+        assert_eq!(format_elapsed_ms(12_000), "12s");
+        assert_eq!(format_elapsed_ms(65_000), "1m 05s");
+    }
+
+    #[test]
+    fn preview_is_the_first_non_empty_line_bounded() {
+        assert_eq!(summary_preview("\n\n  first line \nsecond"), "first line");
+        assert!(summary_preview(&"y".repeat(500)).chars().count() <= 160 + 3);
+    }
+
+    #[test]
+    fn outcome_header_names_the_agent_status_time_and_steps() {
+        let text = format_outcome(&outcome(
+            "explorer-2",
+            AgentStatus::Completed,
+            12_000,
+            5,
+            "body",
+        ));
+        assert!(
+            text.starts_with("[Agent 'explorer-2' · completed · 12s · 5 steps]"),
+            "{text}"
+        );
+        assert!(text.ends_with("body"));
+        let one = format_outcome(&outcome("a", AgentStatus::Failed, 1_000, 1, "x"));
+        assert!(one.contains("1 step]"), "{one}");
+    }
+
+    #[test]
+    fn batch_result_summarizes_counts_and_lists_every_agent_in_order() {
+        let text = format_batch_result(&[
+            outcome("explorer", AgentStatus::Completed, 1_000, 2, "found A"),
+            outcome("debugger", AgentStatus::Failed, 2_000, 1, "boom"),
+            outcome("explorer-2", AgentStatus::Cancelled, 0, 0, "not started"),
+        ]);
+        assert!(text.contains("3 agents"), "{text}");
+        assert!(
+            text.contains("1 completed")
+                && text.contains("1 failed")
+                && text.contains("1 cancelled"),
+            "{text}"
+        );
+        let a = text.find("found A").unwrap();
+        let b = text.find("boom").unwrap();
+        let c = text.find("not started").unwrap();
+        assert!(a < b && b < c, "agents must appear in task order");
+    }
+}

package/crates/mint-core/src/swarm/labels.rs

@@ -0,0 +1,100 @@
+//! Unique, filesystem/chat-id-safe labels for agents within one batch.
+use std::collections::HashSet;
+
+/// Reduces arbitrary model-supplied text to a label that is safe inside
+/// `{parent}::subagent::{label}` — ASCII letters/digits/`-`/`_` only, no `::`.
+/// May return an empty string; callers fall back to the profile name.
+pub fn sanitize_label(raw: &str) -> String {
+    let mut out = String::new();
+    let mut pending_dash = false;
+    for ch in raw.trim().chars() {
+        if ch.is_ascii_alphanumeric() || ch == '_' {
+            if pending_dash && !out.is_empty() {
+                out.push('-');
+            }
+            pending_dash = false;
+            out.push(ch.to_ascii_lowercase());
+        } else {
+            pending_dash = true;
+        }
+    }
+    out.truncate(MAX_LABEL_LEN);
+    while out.ends_with('-') {
+        out.pop();
+    }
+    out
+}
+
+const MAX_LABEL_LEN: usize = 40;
+
+/// Hands out labels that never repeat within a batch: `explorer`,
+/// `explorer-2`, `explorer-3`, ...
+#[derive(Debug, Default)]
+pub struct LabelAllocator {
+    used: HashSet<String>,
+}
+
+impl LabelAllocator {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn allocate(&mut self, base: &str) -> String {
+        let mut candidate = base.to_string();
+        let mut n = 2;
+        while self.used.contains(&candidate) {
+            candidate = format!("{base}-{n}");
+            n += 1;
+        }
+        self.used.insert(candidate.clone());
+        candidate
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn first_label_is_plain_and_repeats_get_numeric_suffixes() {
+        let mut labels = LabelAllocator::new();
+        assert_eq!(labels.allocate("explorer"), "explorer");
+        assert_eq!(labels.allocate("explorer"), "explorer-2");
+        assert_eq!(labels.allocate("explorer"), "explorer-3");
+        assert_eq!(labels.allocate("debugger"), "debugger");
+    }
+
+    #[test]
+    fn an_explicit_suffixed_label_is_never_handed_out_twice() {
+        let mut labels = LabelAllocator::new();
+        assert_eq!(labels.allocate("explorer-2"), "explorer-2");
+        assert_eq!(labels.allocate("explorer"), "explorer");
+        assert_eq!(labels.allocate("explorer"), "explorer-3");
+    }
+
+    #[test]
+    fn sanitize_keeps_ascii_words_joined_by_dashes() {
+        assert_eq!(
+            sanitize_label("Stripe Webhook Tracer!"),
+            "stripe-webhook-tracer"
+        );
+        assert_eq!(sanitize_label("  a__b  "), "a__b");
+    }
+
+    #[test]
+    fn sanitize_removes_chat_id_separators() {
+        let label = sanitize_label("evil::subagent::name");
+        assert!(!label.contains(':'), "got {label}");
+    }
+
+    #[test]
+    fn sanitize_returns_empty_when_nothing_usable_remains() {
+        assert_eq!(sanitize_label("ค้นหาโค้ด"), "");
+        assert_eq!(sanitize_label("  !!  "), "");
+    }
+
+    #[test]
+    fn sanitize_caps_length() {
+        assert!(sanitize_label(&"a".repeat(200)).len() <= 40);
+    }
+}

package/crates/mint-core/src/swarm/mod.rs

@@ -0,0 +1,158 @@
+//! Swarm: runs a *batch* of isolated sub-agents for the main agent.
+//!
+//! The main agent hands the harness one `dispatch_agents` call carrying a list
+//! of tasks; this module owns everything about running them — unique labels,
+//! permission scoping, the concurrency cap, the write lane, lifecycle events,
+//! and capping what flows back into the main agent's context. Callers see only
+//! [`run_batch`]; the real agent loop is injected as a `runner` so the whole
+//! module is testable without a model provider.
+//!
+//! Design rules enforced here:
+//! - A sub-agent's permissions come from its **base profile only** — the model
+//!   can name a role, never grant itself more tools (see [`AgentPermissions`]).
+//! - Agents that can mutate state run one at a time (the "write lane");
+//!   read-only agents run in parallel up to the configured cap.
+//! - Every task yields exactly one [`SwarmOutcome`], in task order, and exactly
+//!   one `Started` + one `Finished` event — success, failure and cancellation
+//!   included.
+
+mod batch;
+mod dossier;
+mod labels;
+mod permissions;
+
+pub use batch::{Emitter, run_batch};
+pub use dossier::{
+    MAX_DOSSIER_CHARS, cap_dossier, format_batch_result, format_elapsed_ms, format_outcome,
+    summary_preview,
+};
+pub use labels::{LabelAllocator, sanitize_label};
+pub use permissions::{
+    AgentPermissions, READ_ONLY_ACTIONS, current_permissions, scope_permissions,
+};
+
+use crate::orchestration::AgentProgress;
+use crate::subagents::SubagentDefinition;
+
+/// Parallelism used when the user has not configured `swarmMaxParallel`.
+pub const DEFAULT_MAX_PARALLEL: usize = 4;
+const MIN_MAX_PARALLEL: usize = 1;
+const MAX_MAX_PARALLEL: usize = 8;
+/// Base profile for a task that names none — deliberately the read-only one.
+pub const DEFAULT_BASE: &str = "explorer";
+
+/// The parallelism cap to use: `None` (unset) means [`DEFAULT_MAX_PARALLEL`];
+/// an explicit value is clamped to `1..=8` so a typo cannot hammer the
+/// provider's rate limit or disable concurrency entirely.
+pub fn effective_max_parallel(configured: Option<usize>) -> usize {
+    configured
+        .map(|n| n.clamp(MIN_MAX_PARALLEL, MAX_MAX_PARALLEL))
+        .unwrap_or(DEFAULT_MAX_PARALLEL)
+}
+
+/// One unit of work the main agent asked for.
+#[derive(Debug, Clone, Default)]
+pub struct SwarmTask {
+    /// Display name + focus the model gave this agent (optional).
+    pub role: Option<String>,
+    /// Profile that decides the permissions (optional; defaults to
+    /// [`DEFAULT_BASE`]).
+    pub base: Option<String>,
+    pub instruction: String,
+}
+
+/// Everything a runner needs to execute one agent.
+#[derive(Debug, Clone)]
+pub struct AgentRun {
+    /// Unique within the batch; used in the chat id and UI.
+    pub label: String,
+    /// `{parent}::subagent::{label}` — the marker many modules key off.
+    pub chat_id: String,
+    pub profile: String,
+    pub role: Option<String>,
+    pub instruction: String,
+    pub system_prompt: String,
+    pub permissions: AgentPermissions,
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub sandbox: Option<String>,
+}
+
+/// What a runner returns on success.
+#[derive(Debug, Clone)]
+pub struct RunnerOutput {
+    pub text: String,
+    pub steps: u32,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AgentStatus {
+    Completed,
+    Failed,
+    Cancelled,
+}
+
+impl AgentStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Completed => "completed",
+            Self::Failed => "failed",
+            Self::Cancelled => "cancelled",
+        }
+    }
+}
+
+/// The final record of one agent, handed back to the main agent.
+#[derive(Debug, Clone)]
+pub struct SwarmOutcome {
+    pub label: String,
+    pub profile: String,
+    pub status: AgentStatus,
+    pub elapsed_ms: u64,
+    pub steps: u32,
+    /// Dossier (success) or error text (failure), already capped.
+    pub text: String,
+}
+
+/// Lifecycle + progress stream for the UI.
+#[derive(Debug, Clone)]
+pub enum SwarmEvent {
+    Started {
+        label: String,
+        profile: String,
+        task: String,
+    },
+    /// A nested progress event from inside an agent (tool calls etc.).
+    Progress(AgentProgress),
+    Finished {
+        label: String,
+        status: AgentStatus,
+        elapsed_ms: u64,
+        steps: u32,
+        summary_preview: String,
+    },
+}
+
+/// Per-batch inputs that are not tasks.
+pub struct BatchCtx<'a> {
+    pub parent_chat_id: &'a str,
+    /// Already-effective cap (see [`effective_max_parallel`]).
+    pub max_parallel: usize,
+    /// Resolves a base profile name (builtin or user-authored file).
+    pub profiles: &'a (dyn Fn(&str) -> Option<SubagentDefinition> + Sync),
+    /// True if the parent turn is currently in Plan Mode.
+    pub plan_mode: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn effective_max_parallel_defaults_to_four_and_clamps_explicit_values() {
+        assert_eq!(effective_max_parallel(None), 4);
+        assert_eq!(effective_max_parallel(Some(3)), 3);
+        assert_eq!(effective_max_parallel(Some(0)), 1);
+        assert_eq!(effective_max_parallel(Some(100)), 8);
+    }
+}

package/crates/mint-core/src/swarm/permissions.rs

@@ -0,0 +1,167 @@
+//! What a sub-agent may do. Derived from its base profile's `tools:` list and
+//! nothing else — a model-supplied role name never widens it.
+use std::collections::BTreeSet;
+
+/// Actions known to be pure reads. Anything *not* listed here is treated as
+/// able to mutate state — an allow-list, so a newly added tool defaults to the
+/// safe (serialized) side instead of silently running in parallel.
+pub const READ_ONLY_ACTIONS: &[&str] = &[
+    "list_files",
+    "read_file",
+    "search_code",
+    "symbols",
+    "find_definition",
+    "find_references",
+    "repo_map",
+    "semantic_search",
+    "knowledge_search",
+    "web_search",
+    "memory_recall",
+    "git_status",
+    "git_diff",
+    "git_log",
+    "git_branch",
+    "detect_project",
+    "list_tests",
+    "read_diagnostics",
+    "view_image",
+    "mcp_list_tools",
+    "finish",
+];
+
+/// Tools a sub-agent can never use, whatever its profile says: spawning more
+/// agents (depth limit — subagents never dispatch subagents).
+const NEVER_ALLOWED: &[&str] = &["dispatch_agents", "dispatch_subagent"];
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AgentPermissions {
+    /// `None` = the profile declared no restriction (full catalog).
+    allowed: Option<BTreeSet<String>>,
+}
+
+impl AgentPermissions {
+    pub fn unrestricted() -> Self {
+        Self { allowed: None }
+    }
+
+    pub fn from_tools(tools: Option<&[String]>) -> Self {
+        let allowed = tools.map(|list| {
+            let mut set: BTreeSet<String> = list
+                .iter()
+                .map(|t| t.trim().to_string())
+                .filter(|t| !t.is_empty() && !NEVER_ALLOWED.contains(&t.as_str()))
+                .collect();
+            // An agent must always be able to hand its result back.
+            set.insert("finish".to_string());
+            set
+        });
+        Self { allowed }
+    }
+
+    pub fn allows(&self, action: &str) -> bool {
+        if NEVER_ALLOWED.contains(&action) {
+            return false;
+        }
+        match &self.allowed {
+            None => true,
+            Some(set) => set.contains(action),
+        }
+    }
+
+    /// Whether this agent could change workspace/system state and must
+    /// therefore take the single write lane.
+    pub fn is_write_capable(&self) -> bool {
+        match &self.allowed {
+            None => true,
+            Some(set) => set.iter().any(|a| !READ_ONLY_ACTIONS.contains(&a.as_str())),
+        }
+    }
+
+    pub fn allowed_actions(&self) -> Option<&BTreeSet<String>> {
+        self.allowed.as_ref()
+    }
+}
+
+tokio::task_local! {
+    static CURRENT_PERMISSIONS: Option<AgentPermissions>;
+}
+
+pub async fn scope_permissions<F: std::future::Future>(
+    permissions: Option<AgentPermissions>,
+    future: F,
+) -> F::Output {
+    CURRENT_PERMISSIONS.scope(permissions, future).await
+}
+
+pub fn current_permissions() -> Option<AgentPermissions> {
+    CURRENT_PERMISSIONS.try_with(|p| p.clone()).ok().flatten()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::subagents::builtin_subagents;
+
+    fn builtin_permissions(name: &str) -> AgentPermissions {
+        let def = builtin_subagents()
+            .into_iter()
+            .find(|d| d.name == name)
+            .unwrap_or_else(|| panic!("no builtin {name}"));
+        AgentPermissions::from_tools(def.tools.as_deref())
+    }
+
+    #[test]
+    fn explorer_is_read_only_and_cannot_write_or_shell() {
+        let p = builtin_permissions("explorer");
+        assert!(p.allows("read_file"));
+        assert!(p.allows("search_code"));
+        assert!(!p.allows("write_file"));
+        assert!(!p.allows("apply_patch"));
+        assert!(!p.allows("run_shell"));
+        assert!(!p.is_write_capable());
+    }
+
+    #[test]
+    fn debugger_may_run_commands_but_not_edit_files() {
+        let p = builtin_permissions("debugger");
+        assert!(p.allows("run_shell"));
+        assert!(!p.allows("write_file"));
+        assert!(!p.allows("apply_patch"));
+        assert!(
+            p.is_write_capable(),
+            "run_shell can mutate, so it takes the write lane"
+        );
+    }
+
+    #[test]
+    fn unrestricted_profiles_are_write_capable() {
+        let p = AgentPermissions::unrestricted();
+        assert!(p.allows("write_file"));
+        assert!(p.is_write_capable());
+    }
+
+    #[test]
+    fn finish_is_always_allowed_even_with_an_empty_list() {
+        let p = AgentPermissions::from_tools(Some(&[]));
+        assert!(p.allows("finish"));
+        assert!(!p.allows("read_file"));
+        assert!(!p.is_write_capable());
+    }
+
+    #[test]
+    fn spawning_agents_is_never_allowed_even_when_unrestricted() {
+        for p in [
+            AgentPermissions::unrestricted(),
+            AgentPermissions::from_tools(Some(&["dispatch_agents".to_string()])),
+        ] {
+            assert!(!p.allows("dispatch_agents"));
+            assert!(!p.allows("dispatch_subagent"));
+        }
+    }
+
+    #[test]
+    fn an_unknown_tool_in_the_list_counts_as_write_capable() {
+        let p = AgentPermissions::from_tools(Some(&["brand_new_tool".to_string()]));
+        assert!(p.is_write_capable());
+    }
+}