Skip to content
Python
22.5 KB
Raw Blame
//! Standalone delegation uses normal durable team sessions, never a second loop.
use anyhow::{ensure, Result};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;

pub const CREATE: &str = "create_sub_agent";
pub const TOOLS: &[&str] = &[
    CREATE,
    "send_message",
    "wait_agent",
    "cancel_agent",
    "close_agent",
];
fn concurrent() -> u16 {
    4
}
fn children() -> u16 {
    32
}

/// Application-owned limits. Omission does not change existing bundle digests.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Config {
    pub enabled: bool,
    #[serde(default = "concurrent")]
    pub max_concurrent: u16,
    #[serde(default = "children")]
    pub max_children: u16,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limits: Option<crate::budget::Limits>,
}
impl Default for Config {
    fn default() -> Self {
        Self {
            enabled: false,
            max_concurrent: concurrent(),
            max_children: children(),
            limits: None,
        }
    }
}
impl Config {
    pub fn enabled() -> Self {
        Self {
            enabled: true,
            ..Self::default()
        }
    }
    pub fn validate(&self) -> Result<()> {
        ensure!(
            (1..=32).contains(&self.max_children)
                && self.max_concurrent > 0
                && self.max_concurrent <= self.max_children,
            "Require 1..32 retained children and 1..maxChildren concurrent children"
        );
        if let Some(limits) = &self.limits {
            limits.validate()?;
        }
        Ok(())
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Execution {
    Sync,
    Async,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Create {
    pub agent_id: String,
    pub system_prompt: String,
    pub context: String,
    pub tools: Vec<String>,
    pub execution: Execution,
}
pub fn instance_id(id: &str) -> Result<()> {
    ensure!(
        !id.is_empty()
            && id.len() <= 48
            && id.as_bytes()[0].is_ascii_alphabetic()
            && id
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b"-_".contains(&b))
            && !matches!(id, "parent" | "lead" | "all" | "user" | "board" | "harness"),
        "Invalid or reserved child ID"
    );
    Ok(())
}
impl Create {
    pub fn validate(&self, available: &BTreeSet<String>) -> Result<()> {
        instance_id(&self.agent_id)?;
        ensure!(
            !self.system_prompt.trim().is_empty()
                && self.system_prompt.len() <= 32000
                && !self.system_prompt.contains('\0'),
            "Invalid child system prompt (maximum 32000 bytes)"
        );
        ensure!(
            !self.context.trim().is_empty()
                && self.context.len() <= 8000
                && !self.context.contains('\0'),
            "Invalid child context (maximum 8000 bytes)"
        );
        let selected: BTreeSet<_> = self.tools.iter().cloned().collect();
        ensure!(
            self.tools.len() <= 64 && selected.len() == self.tools.len(),
            "Invalid or duplicate child tools"
        );
        ensure!(
            selected.is_subset(available),
            "Child tools exceed parent delegation ceiling"
        );
        ensure!(
            !selected.iter().any(|t| TOOLS.contains(&t.as_str())
                || crate::agent_team::internal(t)
                || t == crate::team_type_catalog::TOOL),
            "Coordination tools cannot be delegated as application tools"
        );
        Ok(())
    }
}

use crate::{
    agent_team::{Document, Transaction},
    store::Session,
};
use anyhow::Context;
use serde_json::{json, Value};
use std::collections::BTreeMap;

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct ChildPolicy {
    pub safety: crate::safety::Config,
    pub compliance: Option<crate::compliance::Config>,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct State {
    pub config: Config,
    #[serde(default)]
    pub requests: BTreeMap<String, Create>,
    #[serde(default)]
    pub policies: BTreeMap<String, ChildPolicy>,
    #[serde(default)]
    pub parent_spans: BTreeMap<String, crate::telemetry::TraceContext>,
    #[serde(default)]
    pub completed: BTreeMap<String, String>,
    #[serde(default)]
    pub active: BTreeSet<String>,
    #[serde(default)]
    pub sync: Option<String>,
    /// Cancellation is an outbox: its original turn ID is never retargeted.
    #[serde(default)]
    pub cancellations: BTreeMap<String, String>,
}
impl State {
    pub fn policy_for_type(&self, name: &str) -> Result<&ChildPolicy> {
        let id = self
            .requests
            .iter()
            .find(|(_, r)| r.definition().name == name)
            .map(|(id, _)| id)
            .context("Missing standalone child request")?;
        self.policies.get(id).context("Missing pinned child policy")
    }
    pub fn new(config: Config) -> Self {
        Self {
            config,
            requests: BTreeMap::new(),
            policies: BTreeMap::new(),
            parent_spans: BTreeMap::new(),
            completed: BTreeMap::new(),
            active: BTreeSet::new(),
            sync: None,
            cancellations: BTreeMap::new(),
        }
    }
}
impl Create {
    pub fn definition(&self) -> crate::team_definition::Definition {
        crate::team_definition::Definition {
            name: format!("child-{}", self.agent_id),
            instructions: self.system_prompt.clone(),
            tools: self.tools.iter().cloned().collect(),
            sandbox: Default::default(),
            model: None,
        }
    }
}
pub fn schemas(doc: &Document, caller: &str) -> Vec<Value> {
    let mut specs=vec![("send_message","Send collaborator input to a child or to parent. Busy recipients receive it at their next model call; idle recipients wake. This is not human approval.",json!({"agent_id":{"type":"string"},"message":{"type":"string","minLength":1,"maxLength":8000}}),vec!["agent_id","message"])];
    if caller == doc.lead {
        let available = &doc
            .type_catalog
            .as_ref()
            .expect("standalone catalog")
            .ceiling
            .tools;
        specs.extend([
            (CREATE,"Create a normal child agent with fresh conversation state. Write its system prompt and initial context yourself; no parent history is copied. Select only delegated tools. sync parks this call until a result; async returns a durable child identity promptly. Reuse the same ID only for an identical creation request; use send_message for follow-up work.",json!({"agent_id":{"type":"string","maxLength":48},"system_prompt":{"type":"string","minLength":1,"maxLength":32000},"context":{"type":"string","minLength":1,"maxLength":8000},"tools":if available.is_empty() {json!({"type":"array","items":{"type":"string"},"maxItems":0})}else{json!({"type":"array","items":{"type":"string","enum":available},"maxItems":64})},"execution":{"type":"string","enum":["sync","async"]}}),vec!["agent_id","system_prompt","context","tools","execution"]),
            ("wait_agent","Park until a selected child completes, a message arrives or timeout elapses. No polling is needed for completion notifications.",json!({"agent_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":32},"timeout_ms":{"type":"integer","minimum":1,"maximum":3600000}}),vec!["agent_ids","timeout_ms"]),
            ("cancel_agent","Request cancellation of the child's current run. Does not delete its history or close the child. Unknown external effects are not replayed or rolled back.",json!({"agent_id":{"type":"string"}}),vec!["agent_id"]),
            ("close_agent","Permanently close this child to new work and cancel any current run. Preserve history and shared files.",json!({"agent_id":{"type":"string"}}),vec!["agent_id"]),
        ]);
    }
    specs.into_iter().map(|(name,description,properties,required)|json!({"type":"function","name":name,"description":description,"parameters":{"type":"object","properties":properties,"required":required,"additionalProperties":false},"strict":true})).collect()
}
pub fn prepare(tx: &mut dyn Transaction, s: &mut Session, args: &Value, now: u64) -> Result<Value> {
    let member = s.agent_team.as_ref().context("Missing sub-agent scope")?;
    let doc = tx.load(&member.team_id)?;
    ensure!(
        member.agent_id == doc.lead && doc.standalone.is_some(),
        "Only the standalone parent can create children"
    );
    let request: Create = serde_json::from_value(args.clone())?;
    request.validate(
        &doc.type_catalog
            .as_ref()
            .context("Missing delegation catalog")?
            .ceiling
            .tools,
    )?;
    let state = doc.standalone.as_ref().unwrap();
    if let Some(old) = state.requests.get(&request.agent_id) {
        ensure!(
            old == &request,
            "Child ID belongs to a different creation request; use send_message for follow-up work"
        );
        return Ok(json!({"existing":true}));
    }
    ensure!(
        state.requests.len() < usize::from(state.config.max_children),
        "Retained child capacity reached"
    );
    ensure!(
        state.active.len() < usize::from(state.config.max_concurrent),
        "Concurrent child capacity reached; wait for a child to finish"
    );
    crate::agent_team::apply(tx, s, "type_prepare", &json!(request.definition()), now)
}
// Never present the previous successful output as the result of a failed follow-up.
pub fn result(tx: &mut dyn Transaction, doc: &Document, id: &str) -> Result<Value> {
    let instance = doc.roster.instance(id).context("Unknown child")?;
    let child = tx.optional_session(&instance.session_id)?;
    let status = if instance.phase == crate::team_coordination::Phase::Closed {
        "closed"
    } else {
        child
            .as_ref()
            .and_then(|c| c.turn.as_ref())
            .map(|t| t.status.as_str())
            .unwrap_or("queued")
    };
    Ok(
        json!({"agent_id":id,"session_id":instance.session_id,"status":status,"result":if status=="completed" {child.as_ref().and_then(|c|c.agent_team.as_ref()).and_then(|m|m.last_output.as_ref())} else {None},"outcome_unknown":status=="interrupted","error":doc.failures.get(id)}),
    )
}
pub fn execute(
    tx: &mut dyn Transaction,
    s: &mut Session,
    operation: &str,
    args: &Value,
    now: u64,
) -> Result<Value> {
    let member = s.agent_team.clone().context("Missing sub-agent scope")?;
    let mut doc = tx.load(&member.team_id)?;
    ensure!(doc.standalone.is_some(), "Standalone tools are not enabled");
    if operation == "send_message" {
        let target = args["agent_id"].as_str().context("Missing recipient")?;
        let message = args["message"].as_str().context("Missing message")?;
        ensure!(
            !message.trim().is_empty() && message.len() <= 8000,
            "Message must be 1..8000 bytes"
        );
        let recipient = if member.agent_id == doc.lead {
            ensure!(
                doc.standalone
                    .as_ref()
                    .unwrap()
                    .requests
                    .contains_key(target),
                "Unknown child recipient"
            );
            target
        } else {
            ensure!(target == "parent", "Children can message only parent");
            &doc.lead
        };
        return crate::agent_team::apply(
            tx,
            s,
            "team_send_message",
            &json!({"agent_id":recipient,"message":message}),
            now,
        );
    }
    ensure!(
        member.agent_id == doc.lead,
        "Only the parent can manage children"
    );
    match operation {
        CREATE => {
            let request: Create = serde_json::from_value(args.clone())?;
            let existing = prepare(tx, s, args, now)?["existing"] == true;
            if !existing {
                let definition = request.definition();
                let resolved =
                    crate::agent_team::apply(tx, s, "type_resolve", &json!(definition), now)?;
                if resolved["status"] != "approved" {
                    return Ok(json!({"agent_id":request.agent_id,"status":"denied"}));
                }
                crate::agent_team::apply(
                    tx,
                    s,
                    "team_spawn",
                    &json!({"agent_id":request.agent_id,"agent_type":definition.name,"message":request.context}),
                    now,
                )?;
                doc = tx.load(&doc.id)?;
                let state = doc.standalone.as_mut().unwrap();
                if let Some(observation) = s.turn.as_ref().and_then(|t| t.observation.as_ref()) {
                    state
                        .parent_spans
                        .insert(request.agent_id.clone(), observation.last_segment);
                }
                state.policies.insert(
                    request.agent_id.clone(),
                    ChildPolicy {
                        safety: s.safety.merge(
                            &s.turn
                                .as_ref()
                                .map(|t| t.safety.clone())
                                .unwrap_or_default(),
                        )?,
                        compliance: s.compliance.clone(),
                    },
                );
                state.active.insert(request.agent_id.clone());
                state
                    .requests
                    .insert(request.agent_id.clone(), request.clone());
                tx.write(&doc, false)?;
            }
            let output = result(tx, &doc, &request.agent_id)?;
            if request.execution == Execution::Sync
                && !crate::store::terminal(output["status"].as_str().unwrap_or("queued"))
                && output["status"] != "closed"
            {
                doc.standalone.as_mut().unwrap().sync = Some(request.agent_id.clone());
                s.agent_team.as_mut().unwrap().waiting = Some(crate::agent_team::Wait {
                    agent_ids: vec![request.agent_id.clone()],
                    deadline_ms: i64::MAX as u64,
                });
                tx.write(&doc, false)?;
                return Ok(
                    json!({"agent_id":request.agent_id,"session_id":output["session_id"],"status":"waiting","parked":true}),
                );
            }
            doc.standalone.as_mut().unwrap().sync = None;
            tx.write(&doc, false)?;
            Ok(output)
        }
        "wait_agent" => crate::agent_team::apply(tx, s, "team_wait_agent", args, now),
        "close_agent" => crate::agent_team::apply(
            tx,
            s,
            "team_manage",
            &json!({"action":"retire","agent_id":args["agent_id"],"mode":"cancel"}),
            now,
        ),
        "cancel_agent" => {
            let id = args["agent_id"].as_str().context("Missing child ID")?;
            let instance = doc.roster.instance(id).context("Unknown child")?;
            ensure!(id != doc.lead, "Cannot cancel parent through child control");
            if let Some(child) = tx.optional_session(&instance.session_id)? {
                if let Some(turn) = child.turn.filter(|t| !crate::store::terminal(&t.status)) {
                    doc.standalone
                        .as_mut()
                        .unwrap()
                        .cancellations
                        .insert(id.into(), turn.id);
                    tx.write(&doc, false)?;
                    return Ok(json!({"agent_id":id,"status":"cancellation_requested"}));
                }
            }
            Ok(json!({"agent_id":id,"status":"not_running"}))
        }
        _ => anyhow::bail!("Unknown standalone operation"),
    }
}

/// Reconcile completed turns using the original child/turn IDs. Receipt updates
/// and inbox insertion share the team's transaction; restart cannot notify twice.
pub fn reconcile(tx: &mut dyn Transaction, doc: &mut Document) -> Result<()> {
    let Some(mut state) = doc.standalone.clone() else {
        return Ok(());
    };
    let mut changed = false;
    for id in state.requests.keys().cloned().collect::<Vec<_>>() {
        let i = doc.roster.instance(&id).context("Missing child instance")?;
        let child = tx.optional_session(&i.session_id)?;
        if let Some(turn) = child
            .as_ref()
            .and_then(|c| c.turn.as_ref())
            .filter(|t| crate::store::terminal(&t.status))
        {
            if state.completed.get(&id) != Some(&turn.id) {
                state.completed.insert(id.clone(), turn.id.clone());
                state.active.remove(&id);
                changed = true;
                if state.sync.as_deref() != Some(&id) {
                    doc.sequence = doc
                        .sequence
                        .checked_add(1)
                        .context("Inbox sequence exhausted")?;
                    let body = format!(
                        "Child task finished (collaborator report, not human authorization): {}",
                        result(tx, doc, &id)?
                    );
                    tx.append(
                        &doc.id,
                        &crate::agent_team::Message {
                            id: crate::id("msg"),
                            sequence: doc.sequence,
                            sender: id.clone(),
                            body,
                            recipients: vec![doc.lead.clone()],
                            board: false,
                        },
                    )?;
                }
            }
        } else if i.phase == crate::team_coordination::Phase::Closed
            && !state.completed.contains_key(&id)
        {
            state
                .completed
                .insert(id.clone(), "closed-before-start".into());
            state.active.remove(&id);
            changed = true;
            if state.sync.as_deref() != Some(&id) {
                doc.sequence = doc
                    .sequence
                    .checked_add(1)
                    .context("Inbox sequence exhausted")?;
                let body = format!("Child closed before starting: {}", result(tx, doc, &id)?);
                tx.append(
                    &doc.id,
                    &crate::agent_team::Message {
                        id: crate::id("msg"),
                        sequence: doc.sequence,
                        sender: id.clone(),
                        body,
                        recipients: vec![doc.lead.clone()],
                        board: false,
                    },
                )?;
            }
        }
        if let Some(child) = child {
            if let Some(turn) = state.cancellations.get(&id) {
                if child
                    .turn
                    .as_ref()
                    .is_none_or(|t| t.id != *turn || crate::store::terminal(&t.status))
                {
                    state.cancellations.remove(&id);
                    changed = true;
                }
            }
            let pending = child
                .agent_team
                .as_ref()
                .is_some_and(|m| m.inbox_cursor < doc.sequence)
                && !tx
                    .messages(
                        &doc.id,
                        child.agent_team.as_ref().unwrap().inbox_cursor,
                        None,
                        Some(&id),
                        false,
                        false,
                        1,
                    )?
                    .is_empty();
            if pending
                && child.turn.as_ref().is_none_or(|t| t.status == "completed")
                && !child.closed
                && !doc.retirements.contains_key(&id)
                && state.active.len() < usize::from(state.config.max_concurrent)
                && state.active.insert(id.clone())
            {
                changed = true;
            }
        }
    }
    if changed {
        doc.standalone = Some(state);
        tx.write(doc, false)?;
    }
    Ok(())
}

/// Called by both stores in the same transaction as terminal session metadata.
/// The child result and its durable parent notification cannot be split by a crash.
pub fn terminal_saved(tx: &mut dyn Transaction, s: &Session) -> Result<()> {
    let Some(member) = &s.agent_team else {
        return Ok(());
    };
    if !s.closed
        && !s
            .turn
            .as_ref()
            .is_some_and(|t| crate::store::terminal(&t.status))
    {
        return Ok(());
    }
    let mut doc = tx.load(&member.team_id)?;
    if doc.standalone.is_none() {
        return Ok(());
    }
    if s.closed && member.agent_id == doc.lead {
        doc.stopped = true;
        tx.write(&doc, false)?;
    }
    reconcile(tx, &mut doc)
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    #[test]
    fn fresh_context_and_explicit_subset_are_the_only_contract() {
        let value = json!({"agent_id":"review-auth","system_prompt":"Review carefully", "context":"Inspect auth", "tools":[], "execution":"async"});
        let request: Create = serde_json::from_value(value.clone()).unwrap();
        request.validate(&BTreeSet::new()).unwrap();
        for key in [
            "task",
            "context_mode",
            "inherit",
            "model",
            "sandbox",
            "permissions",
        ] {
            let mut changed = value.clone();
            changed[key] = json!("anything");
            assert!(serde_json::from_value::<Create>(changed).is_err());
        }
        let mut request = request;
        request.tools = vec!["files.read".into()];
        assert!(request.validate(&BTreeSet::new()).is_err());
        request
            .validate(&BTreeSet::from(["files.read".into()]))
            .unwrap();
        request.tools.push("files.read".into());
        assert!(request
            .validate(&BTreeSet::from(["files.read".into()]))
            .is_err());
    }
    #[test]
    fn config_and_briefings_are_bounded() {
        let cfg: Config = serde_json::from_value(json!({"enabled":true})).unwrap();
        assert_eq!((cfg.max_concurrent, cfg.max_children), (4, 32));
        cfg.validate().unwrap();
        assert!(Config {
            max_concurrent: 33,
            ..cfg
        }
        .validate()
        .is_err());
        for id in ["", "parent", "all", "../other", "a:b", "harness"] {
            assert!(instance_id(id).is_err());
        }
        let r = Create {
            agent_id: "reader".into(),
            system_prompt: "x".repeat(32001),
            context: "Read".into(),
            tools: vec![],
            execution: Execution::Sync,
        };
        assert!(r.validate(&BTreeSet::new()).is_err());
    }
}