agentguard-local 0.1.0

package/crates/agentguard-core/src/pressure.rs

@@ -0,0 +1,186 @@
+use crate::types::{Policy, PressureState};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MemoryReading {
+    pub used_percent: u8,
+    pub dispatch_warning: bool,
+    pub dispatch_critical: bool,
+    pub pageout_delta: u64,
+    pub swap_used_percent: u8,
+}
+
+impl MemoryReading {
+    pub fn quiet(used_percent: u8) -> Self {
+        Self {
+            used_percent,
+            dispatch_warning: false,
+            dispatch_critical: false,
+            pageout_delta: 0,
+            swap_used_percent: 0,
+        }
+    }
+}
+
+pub fn classify_pressure(policy: &Policy, reading: MemoryReading) -> PressureState {
+    classify_pressure_with_previous(policy, reading, PressureState::Normal)
+}
+
+pub fn classify_pressure_with_previous(
+    policy: &Policy,
+    reading: MemoryReading,
+    previous: PressureState,
+) -> PressureState {
+    if reading.dispatch_critical
+        || reading.used_percent >= policy.critical_memory_pressure_percent
+        || reading.swap_used_percent >= 80
+        || reading.pageout_delta >= 10_000
+    {
+        return PressureState::Critical;
+    }
+    let is_soft_pressure = reading.dispatch_warning
+        || reading.used_percent >= policy.soft_memory_pressure_percent
+        || reading.swap_used_percent >= 50
+        || reading.pageout_delta >= 2_500;
+    let is_recovering_above_threshold = previous != PressureState::Normal
+        && reading.used_percent > policy.recovery_memory_pressure_percent;
+    if is_soft_pressure || is_recovering_above_threshold {
+        PressureState::Soft
+    } else {
+        PressureState::Normal
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PressureHysteresis {
+    state: PressureState,
+    required_recovery_ticks: u32,
+    recovery_ticks: u32,
+}
+
+impl PressureHysteresis {
+    pub fn new(required_recovery_ticks: u32) -> Self {
+        Self {
+            state: PressureState::Normal,
+            required_recovery_ticks: required_recovery_ticks.max(1),
+            recovery_ticks: 0,
+        }
+    }
+
+    pub fn state(&self) -> PressureState {
+        self.state
+    }
+
+    pub fn set_required_recovery_ticks(&mut self, ticks: u32) {
+        self.required_recovery_ticks = ticks.max(1);
+    }
+
+    pub fn observe(&mut self, classified: PressureState) -> PressureState {
+        match (self.state, classified) {
+            (_, PressureState::Critical) => {
+                self.state = PressureState::Critical;
+                self.recovery_ticks = 0;
+            }
+            (PressureState::Critical, PressureState::Soft)
+            | (PressureState::Soft, PressureState::Soft) => {
+                self.state = PressureState::Soft;
+                self.recovery_ticks = 0;
+            }
+            (PressureState::Normal, PressureState::Soft) => {
+                self.state = PressureState::Soft;
+                self.recovery_ticks = 0;
+            }
+            (PressureState::Normal, PressureState::Normal) => {
+                self.recovery_ticks = 0;
+            }
+            (_, PressureState::Normal) => {
+                self.recovery_ticks += 1;
+                if self.recovery_ticks >= self.required_recovery_ticks {
+                    self.state = PressureState::Normal;
+                    self.recovery_ticks = 0;
+                }
+            }
+        }
+        self.state
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pressure_classifier_uses_thresholds_and_events() {
+        let policy = Policy::default();
+        assert_eq!(
+            classify_pressure(&policy, MemoryReading::quiet(40)),
+            PressureState::Normal
+        );
+        assert_eq!(
+            classify_pressure(
+                &policy,
+                MemoryReading::quiet(policy.soft_memory_pressure_percent)
+            ),
+            PressureState::Soft
+        );
+        assert_eq!(
+            classify_pressure(
+                &policy,
+                MemoryReading::quiet(policy.critical_memory_pressure_percent)
+            ),
+            PressureState::Critical
+        );
+        assert_eq!(
+            classify_pressure(
+                &policy,
+                MemoryReading {
+                    dispatch_warning: true,
+                    ..MemoryReading::quiet(10)
+                }
+            ),
+            PressureState::Soft
+        );
+    }
+
+    #[test]
+    fn pressure_recovery_hysteresis_requires_stable_recovery() {
+        let mut tracker = PressureHysteresis::new(3);
+        assert_eq!(
+            tracker.observe(PressureState::Critical),
+            PressureState::Critical
+        );
+        assert_eq!(
+            tracker.observe(PressureState::Normal),
+            PressureState::Critical
+        );
+        assert_eq!(
+            tracker.observe(PressureState::Normal),
+            PressureState::Critical
+        );
+        assert_eq!(
+            tracker.observe(PressureState::Normal),
+            PressureState::Normal
+        );
+    }
+
+    #[test]
+    fn recovery_threshold_keeps_previous_pressure_until_safe() {
+        let policy = Policy::default();
+        assert_eq!(
+            classify_pressure_with_previous(
+                &policy,
+                MemoryReading::quiet(policy.recovery_memory_pressure_percent + 1),
+                PressureState::Critical,
+            ),
+            PressureState::Soft
+        );
+        assert_eq!(
+            classify_pressure_with_previous(
+                &policy,
+                MemoryReading::quiet(policy.recovery_memory_pressure_percent),
+                PressureState::Soft,
+            ),
+            PressureState::Normal
+        );
+    }
+}

package/crates/agentguard-core/src/process.rs

@@ -0,0 +1,100 @@
+use crate::types::ProcessSample;
+use chrono::Utc;
+use std::os::unix::process::{CommandExt, ExitStatusExt};
+use std::process::{Child, Command, ExitStatus};
+
+#[derive(Debug, Clone, Copy)]
+pub enum Signal {
+    Stop,
+    Continue,
+    Terminate,
+}
+
+impl Signal {
+    fn as_raw(self) -> i32 {
+        match self {
+            Signal::Stop => libc::SIGSTOP,
+            Signal::Continue => libc::SIGCONT,
+            Signal::Terminate => libc::SIGTERM,
+        }
+    }
+}
+
+pub fn spawn_in_process_group(command: &str, args: &[String]) -> anyhow::Result<Child> {
+    let mut cmd = Command::new(command);
+    cmd.args(args);
+    // SAFETY: pre_exec runs in the child after fork and before exec. setpgid is
+    // async-signal-safe and makes the child the leader of a fresh process group.
+    unsafe {
+        cmd.pre_exec(|| {
+            if libc::setpgid(0, 0) == -1 {
+                return Err(std::io::Error::last_os_error());
+            }
+            Ok(())
+        });
+    }
+    Ok(cmd.spawn()?)
+}
+
+pub fn send_signal_to_group(pgid: i64, signal: Signal) -> anyhow::Result<()> {
+    let rc = unsafe { libc::killpg(pgid as libc::pid_t, signal.as_raw()) };
+    if rc == -1 {
+        return Err(std::io::Error::last_os_error().into());
+    }
+    Ok(())
+}
+
+pub fn pid_alive(pid: i64) -> bool {
+    let rc = unsafe { libc::kill(pid as libc::pid_t, 0) };
+    rc == 0
+}
+
+pub fn exit_code(status: ExitStatus) -> i32 {
+    if let Some(code) = status.code() {
+        code
+    } else {
+        128 + status.signal().unwrap_or(1)
+    }
+}
+
+pub fn sample_process_group(
+    job_id: &str,
+    pgid: i64,
+    pressure_state: crate::types::PressureState,
+) -> ProcessSample {
+    let output = Command::new("/bin/ps")
+        .args(["-o", "pid=,rss=,pcpu=", "-g", &pgid.to_string()])
+        .output();
+    let mut pid_count = 0_u32;
+    let mut rss_kb = 0_u64;
+    let mut cpu_pct = 0.0_f64;
+
+    if let Ok(output) = output
+        && output.status.success()
+    {
+        let text = String::from_utf8_lossy(&output.stdout);
+        for line in text.lines() {
+            let mut parts = line.split_whitespace();
+            if parts.next().is_none() {
+                continue;
+            }
+            pid_count += 1;
+            if let Some(rss) = parts.next().and_then(|value| value.parse::<u64>().ok()) {
+                rss_kb += rss;
+            }
+            if let Some(cpu) = parts.next().and_then(|value| value.parse::<f64>().ok()) {
+                cpu_pct += cpu;
+            }
+        }
+    }
+
+    ProcessSample {
+        job_id: job_id.to_string(),
+        sampled_at: Utc::now(),
+        pid_count,
+        rss_bytes: rss_kb * 1024,
+        footprint_bytes: rss_kb * 1024,
+        cpu_pct,
+        pressure_state,
+    }
+}

package/crates/agentguard-core/src/protocol.rs

@@ -0,0 +1,186 @@
+use crate::types::{Policy, PressureState, Priority, StatusSnapshot};
+use serde::{Deserialize, Serialize};
+
+pub const PROTOCOL_VERSION: u16 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Request {
+    Admission {
+        protocol_version: u16,
+        adapter: String,
+        command: String,
+        args: Vec<String>,
+        cwd: String,
+        priority: Priority,
+        tty: bool,
+    },
+    LeaseCheck {
+        protocol_version: u16,
+        job_id: String,
+    },
+    Register {
+        protocol_version: u16,
+        job_id: String,
+        root_pid: i64,
+        pgid: i64,
+    },
+    Exit {
+        protocol_version: u16,
+        job_id: String,
+        exit_code: i32,
+    },
+    Status {
+        protocol_version: u16,
+        include_processes: bool,
+    },
+    PolicyGet {
+        protocol_version: u16,
+    },
+    PolicySet {
+        protocol_version: u16,
+        key: String,
+        value: String,
+    },
+    Pause {
+        protocol_version: u16,
+        job_id: String,
+    },
+    Resume {
+        protocol_version: u16,
+        job_id: String,
+    },
+    Cancel {
+        protocol_version: u16,
+        job_id: String,
+    },
+    ToolPathSet {
+        protocol_version: u16,
+        tool: String,
+        real_path: String,
+    },
+    Doctor {
+        protocol_version: u16,
+    },
+    TestSetPressure {
+        protocol_version: u16,
+        pressure: PressureState,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Response {
+    Admission {
+        protocol_version: u16,
+        job_id: String,
+        admitted: bool,
+        state: String,
+        reason: Option<String>,
+        codex_max_threads: u32,
+    },
+    Lease {
+        protocol_version: u16,
+        job_id: String,
+        admitted: bool,
+        state: String,
+        reason: Option<String>,
+    },
+    Ack {
+        protocol_version: u16,
+        message: String,
+    },
+    Status {
+        protocol_version: u16,
+        snapshot: StatusSnapshot,
+    },
+    Policy {
+        protocol_version: u16,
+        policy: Policy,
+    },
+    Doctor {
+        protocol_version: u16,
+        report: DoctorReport,
+    },
+    Error {
+        protocol_version: u16,
+        message: String,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DoctorReport {
+    pub os_supported: bool,
+    pub os: String,
+    pub socket_path: String,
+    pub socket_exists: bool,
+    pub db_path: String,
+    pub db_exists: bool,
+    pub launchd_plist_exists: bool,
+    pub discovered_tools: Vec<(String, String)>,
+}
+
+impl Request {
+    pub fn version(&self) -> u16 {
+        match self {
+            Self::Admission {
+                protocol_version, ..
+            }
+            | Self::LeaseCheck {
+                protocol_version, ..
+            }
+            | Self::Register {
+                protocol_version, ..
+            }
+            | Self::Exit {
+                protocol_version, ..
+            }
+            | Self::Status {
+                protocol_version, ..
+            }
+            | Self::PolicyGet { protocol_version }
+            | Self::PolicySet {
+                protocol_version, ..
+            }
+            | Self::Pause {
+                protocol_version, ..
+            }
+            | Self::Resume {
+                protocol_version, ..
+            }
+            | Self::Cancel {
+                protocol_version, ..
+            }
+            | Self::ToolPathSet {
+                protocol_version, ..
+            }
+            | Self::Doctor { protocol_version }
+            | Self::TestSetPressure {
+                protocol_version, ..
+            } => *protocol_version,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn socket_protocol_serialization_is_versioned_and_compatible() {
+        let request = Request::Admission {
+            protocol_version: PROTOCOL_VERSION,
+            adapter: "codex".to_string(),
+            command: "codex".to_string(),
+            args: vec!["exec".to_string()],
+            cwd: "/tmp".to_string(),
+            priority: Priority::Normal,
+            tty: true,
+        };
+        let json = serde_json::to_string(&request).unwrap();
+        assert!(json.contains("\"protocol_version\":1"));
+        assert!(json.contains("\"type\":\"admission\""));
+        let decoded: Request = serde_json::from_str(&json).unwrap();
+        assert_eq!(decoded.version(), PROTOCOL_VERSION);
+    }
+}

package/crates/agentguard-core/src/scheduler.rs

@@ -0,0 +1,132 @@
+use crate::types::{JobRecord, JobState, Policy, PressureState, Priority};
+use chrono::{DateTime, Utc};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdmissionDecision {
+    Admit,
+    Queue { reason: String },
+}
+
+pub fn decide_admission(
+    policy: &Policy,
+    pressure: PressureState,
+    active_jobs: usize,
+) -> AdmissionDecision {
+    if pressure == PressureState::Critical {
+        return AdmissionDecision::Queue {
+            reason: "critical memory pressure".to_string(),
+        };
+    }
+    if pressure == PressureState::Soft {
+        return AdmissionDecision::Queue {
+            reason: "soft memory pressure".to_string(),
+        };
+    }
+    if active_jobs >= policy.max_active_jobs as usize {
+        return AdmissionDecision::Queue {
+            reason: format!(
+                "active job limit reached ({}/{})",
+                active_jobs, policy.max_active_jobs
+            ),
+        };
+    }
+    AdmissionDecision::Admit
+}
+
+pub fn ordered_queue(mut jobs: Vec<JobRecord>, now: DateTime<Utc>) -> Vec<JobRecord> {
+    jobs.sort_by(|a, b| {
+        let a_score = queue_score(a.priority, a.created_at, now);
+        let b_score = queue_score(b.priority, b.created_at, now);
+        b_score
+            .cmp(&a_score)
+            .then_with(|| a.created_at.cmp(&b.created_at))
+            .then_with(|| a.id.cmp(&b.id))
+    });
+    jobs
+}
+
+fn queue_score(priority: Priority, queued_at: DateTime<Utc>, now: DateTime<Utc>) -> i64 {
+    let wait_minutes = (now - queued_at).num_minutes().max(0);
+    priority.scheduler_weight() + wait_minutes.min(30)
+}
+
+pub fn pause_candidates(jobs: &[JobRecord]) -> Vec<JobRecord> {
+    let mut candidates: Vec<_> = jobs
+        .iter()
+        .filter(|job| job.status == JobState::Running)
+        .cloned()
+        .collect();
+    candidates.sort_by(|a, b| {
+        a.priority
+            .cmp(&b.priority)
+            .then_with(|| a.started_at.cmp(&b.started_at))
+            .then_with(|| a.id.cmp(&b.id))
+    });
+    candidates
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::JobRecord;
+    use chrono::Duration;
+
+    fn job(id: &str, priority: Priority, created_at: DateTime<Utc>) -> JobRecord {
+        let policy = Policy::default();
+        let mut job = JobRecord::new_admission(
+            id.to_string(),
+            "fake".to_string(),
+            "fake".to_string(),
+            vec![],
+            ".".to_string(),
+            priority,
+            &policy,
+        )
+        .unwrap();
+        job.created_at = created_at;
+        job.status = JobState::Queued;
+        job
+    }
+
+    #[test]
+    fn scheduler_admits_under_normal_pressure() {
+        let policy = Policy::default();
+        assert_eq!(
+            decide_admission(&policy, PressureState::Normal, 0),
+            AdmissionDecision::Admit
+        );
+    }
+
+    #[test]
+    fn scheduler_queues_under_soft_pressure() {
+        let policy = Policy::default();
+        assert_eq!(
+            decide_admission(&policy, PressureState::Soft, 0),
+            AdmissionDecision::Queue {
+                reason: "soft memory pressure".to_string()
+            }
+        );
+    }
+
+    #[test]
+    fn scheduler_selects_low_priority_for_critical_pause_first() {
+        let now = Utc::now();
+        let mut low = job("low", Priority::Low, now);
+        let mut high = job("high", Priority::High, now);
+        low.status = JobState::Running;
+        high.status = JobState::Running;
+        let candidates = pause_candidates(&[high, low]);
+        assert_eq!(candidates[0].id, "low");
+    }
+
+    #[test]
+    fn priority_ordering_allows_simple_aging() {
+        let now = Utc::now();
+        let old_low = job("old-low", Priority::Low, now - Duration::minutes(30));
+        let fresh_normal = job("fresh-normal", Priority::Normal, now);
+        let fresh_high = job("fresh-high", Priority::High, now);
+        let ordered = ordered_queue(vec![fresh_normal, old_low, fresh_high], now);
+        assert_eq!(ordered[0].id, "old-low");
+        assert_eq!(ordered[1].id, "fresh-high");
+    }
+}