Skip to content
Python
6.7 KB
Raw Blame
//! Retirement is a durable admission gate, separate from cancelling one turn.
//! Cleanup uses the owning runtime; this module never deletes an environment.
use crate::{
    agent_team::{Document, Transaction},
    store::Session,
    team_coordination::Phase,
};
use anyhow::{ensure, Context, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Mode {
    #[default]
    FinishCurrent,
    Cancel,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Retirement {
    pub mode: Mode,
    pub requested_at_ms: u64,
    pub settled_at_ms: Option<u64>,
    #[serde(default)]
    pub pending_reason: Option<String>,
    /// Original turn may finish already accepted async handoffs; retirement
    /// never admits a later turn or resurrects a cancelled effect.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub turn_id: Option<String>,
}
fn limit() -> usize {
    50
}
#[derive(Deserialize)]
#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
pub enum Request {
    List {
        #[serde(default)]
        after: Option<String>,
        #[serde(default = "limit")]
        limit: usize,
    },
    Retire {
        agent_id: String,
        #[serde(default)]
        mode: Mode,
    },
}
pub fn apply(
    tx: &mut dyn Transaction,
    doc: &mut Document,
    caller: &str,
    args: &Value,
    now: u64,
) -> Result<Value> {
    ensure!(caller == doc.lead, "Only the lead manages team membership");
    match serde_json::from_value::<Request>(args.clone())? {
        Request::List { after, limit } => {
            ensure!(
                (1..=100).contains(&limit),
                "Roster page requires 1..100 entries"
            );
            if let Some(id) = &after {
                ensure!(doc.roster.instance(id).is_some(), "Unknown roster cursor");
            }
            let rows: Vec<_> = doc
                .roster
                .instances()
                .filter(|i| after.as_ref().is_none_or(|id| i.agent_id > *id))
                .take(limit + 1)
                .collect();
            let more = rows.len() > limit;
            let mut members = vec![];
            for i in rows.into_iter().take(limit) {
                let s = tx.optional_session(&i.session_id)?;
                members.push(json!({"instance":i,"title":doc.roster.request(&i.agent_id).and_then(|r|r.title.as_ref()),"type_revision":doc.type_bindings.get(&i.agent_id),"retirement":doc.retirements.get(&i.agent_id),"error":doc.failures.get(&i.agent_id),
                    "workspace":s.as_ref().map(|s|&s.workspace),
                    "last_outcome":s.as_ref().and_then(|s|s.turn.as_ref()).map(|t|&t.status),
                    "outcome_unknown":s.as_ref().and_then(|s|s.turn.as_ref()).is_some_and(|t|t.status=="interrupted") || doc.workspaces.get(&i.agent_id).is_some_and(|w|w.error.is_some()),
                    "model":s.as_ref().map(|s|json!({"connection":s.model_selection.as_ref().map(|m|&m.connection),"model":s.model})),
                    "environment":s.as_ref().and_then(|s|s.environment.as_ref()).map(|e|json!({"id":e.environment_id,"provider":e.spec.provider,"remote_id":e.remote_id}))
                }));
            }
            let next = more.then(|| members.last().unwrap()["instance"]["agent_id"].clone());
            Ok(json!({"members":members,"next":next}))
        }
        Request::Retire { agent_id, mode } => {
            ensure!(agent_id != doc.lead, "Stop the team to retire its lead");
            let member = doc.roster.instance(&agent_id).context("Unknown instance")?;
            if let Some(saved) = doc.retirements.get(&agent_id) {
                ensure!(saved.mode==mode,"Retirement mode already pinned; use the normal turn cancellation API to interrupt current work");
            } else {
                ensure!(member.phase != Phase::Closed, "Instance already closed");
                let turn_id = tx
                    .optional_session(&member.session_id)?
                    .and_then(|s| s.turn.map(|t| t.id));
                doc.roster.retire(&agent_id)?;
                doc.retirements.insert(
                    agent_id.clone(),
                    Retirement {
                        mode,
                        requested_at_ms: now,
                        settled_at_ms: None,
                        pending_reason: None,
                        turn_id,
                    },
                );
            }
            Ok(
                json!({"instance":doc.roster.instance(&agent_id),"retirement":doc.retirements.get(&agent_id)}),
            )
        }
    }
}
/// The runtime must have finished cleanup and persisted session closure before
/// releasing capacity. An unprovisioned reservation has no session to close.
pub fn settle(tx: &mut dyn Transaction, doc: &mut Document, id: &str, now: u64) -> Result<Value> {
    let member = doc.roster.instance(id).context("Unknown instance")?;
    let retirement = doc.retirements.get(id).context("No retirement request")?;
    if retirement.settled_at_ms.is_some() {
        return Ok(json!({"settled":true,"agent_id":id}));
    }
    ensure!(member.phase == Phase::Retiring, "Instance is not retiring");
    if let Some(s) = tx.optional_session(&member.session_id)? {
        ensure!(
            s.closed
                && s.turn
                    .as_ref()
                    .is_none_or(|t| crate::store::terminal(&t.status)),
            "Member work/cleanup has not settled"
        );
    }
    doc.roster.close(id)?;
    let retirement = doc.retirements.get_mut(id).unwrap();
    retirement.settled_at_ms = Some(now);
    retirement.pending_reason = None;
    Ok(json!({"settled":true,"agent_id":id}))
}
pub fn admits(doc: &Document, s: &Session) -> bool {
    !doc.stopped
        && s.agent_team
            .as_ref()
            .and_then(|m| doc.roster.instance(&m.agent_id))
            .is_some_and(|i| i.session_id == s.id && i.phase == Phase::Ready)
}
/// Continuation of an already approved durable operation, never admission for a
/// new tool action. Other profile/credential/cancellation fences still apply.
pub fn accepted_effect(doc: &Document, agent: &str, turn: &str) -> bool {
    doc.roster
        .instance(agent)
        .is_some_and(|i| i.phase == Phase::Ready)
        || doc
            .retirements
            .get(agent)
            .is_some_and(|r| r.mode == Mode::FinishCurrent && r.turn_id.as_deref() == Some(turn))
}
pub fn schema() -> Value {
    json!({"action":{"type":"string","enum":["list","retire"]},"agent_id":{"type":"string"},"mode":{"type":"string","enum":["finish_current","cancel"]},"after":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100}})
}