agentguard-local 0.1.0

package/Cargo.toml

@@ -0,0 +1,22 @@
+[workspace]
+members = ["crates/agentguard-core", "crates/agentguard"]
+resolver = "3"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2024"
+license = "MIT OR Apache-2.0"
+authors = ["AgentGuard contributors"]
+
+[workspace.dependencies]
+agentguard-core = { path = "crates/agentguard-core" }
+anyhow = "1.0.100"
+chrono = { version = "0.4.42", features = ["serde"] }
+clap = { version = "4.5.53", features = ["derive", "env"] }
+libc = "0.2.178"
+rusqlite = { version = "0.37.0", features = ["bundled", "chrono", "serde_json"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.145"
+tempfile = "3.23.0"
+thiserror = "2.0.17"
+uuid = { version = "1.19.0", features = ["v4", "serde"] }

package/README.md

@@ -0,0 +1,140 @@
+# AgentGuard
+
+AgentGuard is a macOS-first local admission controller for AI coding CLI processes. It starts guarded jobs only when local policy and memory pressure allow it, queues new guarded work when the machine is under stress, pauses guarded process groups on critical pressure, and explains those decisions through a small CLI.
+
+AgentGuard is not an agent orchestrator, worktree manager, sandbox, cloud IDE, RAM cleaner, or process killer for arbitrary apps. It only manages jobs launched through `agentguard run` or an installed AgentGuard shim.
+
+## What ships in this MVP
+
+- `agentguardd`: launchd-friendly user daemon with a user-only Unix domain socket.
+- `agentguard`: CLI for `status`, `run`, `policy`, `pause`, `resume`, `cancel`, `doctor`, and `install-shim`.
+- SQLite state for jobs, process samples, events, policy, and tool path mappings.
+- Pure scheduler and policy modules with deterministic tests.
+- Process-group spawning with `SIGSTOP` and `SIGCONT` for guarded jobs only.
+- Codex adapter that injects `-c agents.max_threads=N` unless the user already supplied an explicit `agents.max_threads` config.
+- Deterministic fake pressure support for tests through `AGENTGUARD_FAKE_PRESSURE_FILE`.
+
+## Install
+
+The npm package currently ships prebuilt binaries for macOS on Apple Silicon:
+
+```sh
+npm install -g agentguard-local
+```
+
+The npm package is named `agentguard-local` to avoid collisions with existing packages. It installs the `agentguard` and `agentguardd` commands.
+
+Then start the daemon:
+
+```sh
+agentguardd \
+  --socket "$HOME/.agentguard/agentguard.sock" \
+  --db "$HOME/.agentguard/state.db" \
+  --foreground
+```
+
+## Build From Source
+
+```sh
+cargo build --workspace --all-features
+```
+
+If Cargo is not on `PATH`, install Rust first. On macOS with Homebrew:
+
+```sh
+brew install rust
+```
+
+## Run The Daemon
+
+Foreground mode is easiest while testing from a source checkout:
+
+```sh
+target/debug/agentguardd \
+  --socket "$HOME/.agentguard/agentguard.sock" \
+  --db "$HOME/.agentguard/state.db" \
+  --foreground
+```
+
+The daemon listens only on a local Unix domain socket and stores state in SQLite. It does not open a TCP listener.
+
+## Use The CLI
+
+Check status:
+
+```sh
+target/debug/agentguard status
+target/debug/agentguard status --json
+```
+
+Run a guarded command:
+
+```sh
+target/debug/agentguard run -- /bin/echo hello
+target/debug/agentguard run --priority low -- /bin/sleep 30
+```
+
+Manage policy:
+
+```sh
+target/debug/agentguard policy get
+target/debug/agentguard policy set max_active_jobs 1
+target/debug/agentguard policy set pause_enabled true
+```
+
+Pause, resume, or cancel a guarded job:
+
+```sh
+target/debug/agentguard pause <job-id>
+target/debug/agentguard resume <job-id>
+target/debug/agentguard cancel <job-id>
+```
+
+Run diagnostics:
+
+```sh
+target/debug/agentguard doctor
+```
+
+## Install A Temporary Shim
+
+Install a shim for a real tool path into a directory you control:
+
+```sh
+target/debug/agentguard install-shim codex \
+  --real-path /path/to/real/codex \
+  --shim-dir "$HOME/.agentguard/bin"
+```
+
+Then put the shim directory before the real tool in `PATH`:
+
+```sh
+export PATH="$HOME/.agentguard/bin:$PATH"
+```
+
+The shim dispatches through `agentguard run`, preserves cwd/env/stdin/stdout/stderr/args/exit code, and avoids PATH recursion by storing the real binary path.
+
+## Uninstall
+
+Stop any foreground `agentguardd` process, remove the shim directory from `PATH`, and delete the local data directory if you no longer want state:
+
+```sh
+rm -rf "$HOME/.agentguard"
+```
+
+If you later add a launchd plist, unload and remove it before deleting state.
+
+## Safety Model
+
+- AgentGuard never pauses, resumes, cancels, or kills unguarded user processes.
+- Automatic pause/resume uses process-group signals only for jobs that AgentGuard admitted and registered.
+- Cancel sends `SIGTERM` only to the guarded process group for the selected job.
+- Job commands and events are stored locally in SQLite. Prompts are not separately captured.
+- The v1 control plane is a user-only Unix socket with `0600` permissions.
+
+## Limitations
+
+- v1 does not queue individual Codex subagents after Codex is already running. It caps fan-out at launch.
+- The current system pressure sampler uses stable macOS command output as a documented fallback while preserving the sampler boundary for native API work.
+- There is no menu bar UI, cloud offload, container runtime, microVM dependency, or team dashboard.
+- Pause does not immediately free all memory; it stops execution so pressure can recover.

package/crates/agentguard/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "agentguard"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+
+[dependencies]
+agentguard-core.workspace = true
+anyhow.workspace = true
+clap.workspace = true
+serde_json.workspace = true
+
+[[bin]]
+name = "agentguard"
+path = "src/bin/agentguard.rs"
+
+[[bin]]
+name = "agentguardd"
+path = "src/bin/agentguardd.rs"
+
+[dev-dependencies]
+tempfile.workspace = true

package/crates/agentguard/src/bin/agentguard.rs

@@ -0,0 +1,460 @@
+use agentguard_core::adapter::codex;
+use agentguard_core::process::{exit_code, spawn_in_process_group};
+use agentguard_core::protocol::{DoctorReport, PROTOCOL_VERSION, Request, Response};
+use agentguard_core::server::{default_db_path, default_socket_path};
+use agentguard_core::store::Store;
+use agentguard_core::types::{Priority, StatusSnapshot};
+use clap::{Parser, Subcommand};
+use std::io::{BufRead, BufReader, Write};
+use std::os::unix::net::UnixStream;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "agentguard",
+    about = "RAM-aware admission control for local AI coding agents"
+)]
+struct Cli {
+    #[arg(long, env = "AGENTGUARD_SOCKET", global = true)]
+    socket: Option<PathBuf>,
+    #[arg(long, env = "AGENTGUARD_DB", global = true)]
+    db: Option<PathBuf>,
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Debug, Subcommand)]
+enum Commands {
+    Status {
+        #[arg(long)]
+        json: bool,
+    },
+    Run {
+        #[arg(long, default_value = "normal")]
+        priority: String,
+        #[arg(long, hide = true)]
+        adapter: Option<String>,
+        #[arg(long, hide = true)]
+        real_path: Option<PathBuf>,
+        #[arg(trailing_var_arg = true, required = true, num_args = 1..)]
+        command: Vec<String>,
+    },
+    Policy {
+        #[command(subcommand)]
+        command: PolicyCommand,
+    },
+    Pause {
+        job_id: String,
+    },
+    Resume {
+        job_id: String,
+    },
+    Cancel {
+        job_id: String,
+    },
+    Doctor,
+    InstallShim {
+        tool_name: String,
+        #[arg(long)]
+        real_path: PathBuf,
+        #[arg(long)]
+        shim_dir: PathBuf,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum PolicyCommand {
+    Get,
+    Set { key: String, value: String },
+}
+
+fn main() -> anyhow::Result<()> {
+    let cli = Cli::parse();
+    let socket = cli.socket.unwrap_or_else(default_socket_path);
+    let db = cli.db.unwrap_or_else(default_db_path);
+    match cli.command {
+        Commands::Status { json } => status(&socket, json),
+        Commands::Run {
+            priority,
+            adapter,
+            real_path,
+            command,
+        } => run_command(&socket, priority, adapter, real_path, command),
+        Commands::Policy { command } => policy(&socket, command),
+        Commands::Pause { job_id } => ack(
+            &socket,
+            Request::Pause {
+                protocol_version: PROTOCOL_VERSION,
+                job_id,
+            },
+        ),
+        Commands::Resume { job_id } => ack(
+            &socket,
+            Request::Resume {
+                protocol_version: PROTOCOL_VERSION,
+                job_id,
+            },
+        ),
+        Commands::Cancel { job_id } => ack(
+            &socket,
+            Request::Cancel {
+                protocol_version: PROTOCOL_VERSION,
+                job_id,
+            },
+        ),
+        Commands::Doctor => doctor(&socket, &db),
+        Commands::InstallShim {
+            tool_name,
+            real_path,
+            shim_dir,
+        } => install_shim(&socket, &db, &tool_name, &real_path, &shim_dir),
+    }
+}
+
+fn status(socket: &Path, json: bool) -> anyhow::Result<()> {
+    match send(
+        socket,
+        Request::Status {
+            protocol_version: PROTOCOL_VERSION,
+            include_processes: true,
+        },
+    )? {
+        Response::Status { snapshot, .. } => {
+            if json {
+                println!("{}", serde_json::to_string_pretty(&snapshot)?);
+            } else {
+                print_status(&snapshot);
+            }
+        }
+        response => handle_unexpected(response)?,
+    }
+    Ok(())
+}
+
+fn run_command(
+    socket: &Path,
+    priority: String,
+    adapter: Option<String>,
+    real_path: Option<PathBuf>,
+    command: Vec<String>,
+) -> anyhow::Result<()> {
+    let priority: Priority = priority.parse().map_err(anyhow::Error::msg)?;
+    let display_command = command
+        .first()
+        .ok_or_else(|| anyhow::anyhow!("missing command after --"))?
+        .clone();
+    let display_args = command.iter().skip(1).cloned().collect::<Vec<_>>();
+    let adapter = adapter.unwrap_or_else(|| {
+        Path::new(&display_command)
+            .file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or(&display_command)
+            .to_string()
+    });
+    let cwd = std::env::current_dir()?.display().to_string();
+
+    let admission = send(
+        socket,
+        Request::Admission {
+            protocol_version: PROTOCOL_VERSION,
+            adapter: adapter.clone(),
+            command: display_command.clone(),
+            args: display_args.clone(),
+            cwd,
+            priority,
+            tty: true,
+        },
+    )?;
+
+    let (job_id, mut codex_max_threads) = match admission {
+        Response::Admission {
+            job_id,
+            admitted,
+            reason,
+            codex_max_threads,
+            ..
+        } => {
+            if !admitted {
+                eprintln!(
+                    "agentguard: queued {job_id}: {}",
+                    reason.as_deref().unwrap_or("waiting for admission")
+                );
+                wait_for_lease(socket, &job_id)?;
+            }
+            (job_id, codex_max_threads)
+        }
+        response => handle_unexpected(response)?,
+    };
+
+    if codex_max_threads == 0 {
+        codex_max_threads = 1;
+    }
+    let spawn_command = real_path
+        .as_ref()
+        .map(|path| path.display().to_string())
+        .unwrap_or(display_command);
+    let mut spawn_args = display_args;
+    if adapter == "codex" {
+        spawn_args = codex::apply_thread_cap(&spawn_args, codex_max_threads);
+    }
+
+    let mut child = spawn_in_process_group(&spawn_command, &spawn_args)?;
+    let root_pid = child.id() as i64;
+    let pgid = root_pid;
+    let _ = send(
+        socket,
+        Request::Register {
+            protocol_version: PROTOCOL_VERSION,
+            job_id: job_id.clone(),
+            root_pid,
+            pgid,
+        },
+    );
+    let status = child.wait()?;
+    let code = exit_code(status);
+    let _ = send(
+        socket,
+        Request::Exit {
+            protocol_version: PROTOCOL_VERSION,
+            job_id,
+            exit_code: code,
+        },
+    );
+    std::process::exit(code);
+}
+
+fn wait_for_lease(socket: &Path, job_id: &str) -> anyhow::Result<()> {
+    let mut last_reason = String::new();
+    loop {
+        std::thread::sleep(Duration::from_millis(250));
+        match send(
+            socket,
+            Request::LeaseCheck {
+                protocol_version: PROTOCOL_VERSION,
+                job_id: job_id.to_string(),
+            },
+        )? {
+            Response::Lease {
+                admitted,
+                state,
+                reason,
+                ..
+            } => {
+                if admitted {
+                    return Ok(());
+                }
+                if matches!(state.as_str(), "cancelled" | "failed" | "lost" | "exited") {
+                    anyhow::bail!("queued job ended before admission with state {state}");
+                }
+                let reason = reason.unwrap_or_else(|| "waiting for admission".to_string());
+                if reason != last_reason {
+                    eprintln!("agentguard: still queued {job_id}: {reason}");
+                    last_reason = reason;
+                }
+            }
+            response => handle_unexpected(response)?,
+        }
+    }
+}
+
+fn policy(socket: &Path, command: PolicyCommand) -> anyhow::Result<()> {
+    let request = match command {
+        PolicyCommand::Get => Request::PolicyGet {
+            protocol_version: PROTOCOL_VERSION,
+        },
+        PolicyCommand::Set { key, value } => Request::PolicySet {
+            protocol_version: PROTOCOL_VERSION,
+            key,
+            value,
+        },
+    };
+    match send(socket, request)? {
+        Response::Policy { policy, .. } => {
+            println!("{}", serde_json::to_string_pretty(&policy)?);
+        }
+        response => handle_unexpected(response)?,
+    }
+    Ok(())
+}
+
+fn ack(socket: &Path, request: Request) -> anyhow::Result<()> {
+    match send(socket, request)? {
+        Response::Ack { message, .. } => println!("{message}"),
+        response => handle_unexpected(response)?,
+    }
+    Ok(())
+}
+
+fn doctor(socket: &Path, db: &Path) -> anyhow::Result<()> {
+    match send(
+        socket,
+        Request::Doctor {
+            protocol_version: PROTOCOL_VERSION,
+        },
+    ) {
+        Ok(Response::Doctor { report, .. }) => print_doctor(&report),
+        Ok(response) => handle_unexpected(response)?,
+        Err(_) => {
+            let report = local_doctor(socket, db)?;
+            print_doctor(&report);
+        }
+    }
+    Ok(())
+}
+
+fn install_shim(
+    socket: &Path,
+    db: &Path,
+    tool_name: &str,
+    real_path: &Path,
+    shim_dir: &Path,
+) -> anyhow::Result<()> {
+    anyhow::ensure!(
+        real_path.exists(),
+        "real path does not exist: {}",
+        real_path.display()
+    );
+    std::fs::create_dir_all(shim_dir)?;
+    let agentguard = std::env::current_exe()?;
+    let shim_path = shim_dir.join(tool_name);
+    let script = format!(
+        "#!/bin/sh\nexec {} --socket {} run --adapter {} --real-path {} -- {} \"$@\"\n",
+        shell_quote(&agentguard.display().to_string()),
+        shell_quote(&socket.display().to_string()),
+        shell_quote(tool_name),
+        shell_quote(&real_path.display().to_string()),
+        shell_quote(tool_name),
+    );
+    std::fs::write(&shim_path, script)?;
+    let mut perms = std::fs::metadata(&shim_path)?.permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        perms.set_mode(0o755);
+    }
+    std::fs::set_permissions(&shim_path, perms)?;
+
+    let request = Request::ToolPathSet {
+        protocol_version: PROTOCOL_VERSION,
+        tool: tool_name.to_string(),
+        real_path: real_path.display().to_string(),
+    };
+    if send(socket, request).is_err() {
+        let store = Store::open(db)?;
+        store.set_tool_path(tool_name, &real_path.display().to_string())?;
+    }
+    println!("{}", shim_path.display());
+    Ok(())
+}
+
+fn send(socket: &Path, request: Request) -> anyhow::Result<Response> {
+    let mut stream = UnixStream::connect(socket).map_err(|err| {
+        anyhow::anyhow!(
+            "could not connect to daemon at {}: {err}. Start agentguardd first.",
+            socket.display()
+        )
+    })?;
+    serde_json::to_writer(&mut stream, &request)?;
+    stream.write_all(b"\n")?;
+    stream.flush()?;
+
+    let mut reader = BufReader::new(stream);
+    let mut line = String::new();
+    reader.read_line(&mut line)?;
+    let response: Response = serde_json::from_str(&line)?;
+    if let Response::Error { message, .. } = &response {
+        anyhow::bail!("{message}");
+    }
+    Ok(response)
+}
+
+fn print_status(snapshot: &StatusSnapshot) {
+    println!("Pressure: {}", snapshot.pressure);
+    println!(
+        "Policy: max_active_jobs={}, codex_threads={}, pause_enabled={}",
+        snapshot.policy.max_active_jobs,
+        snapshot.policy.default_codex_max_threads,
+        snapshot.policy.pause_enabled
+    );
+    println!("Jobs:");
+    if snapshot.jobs.is_empty() {
+        println!("  none");
+    }
+    for job in &snapshot.jobs {
+        let reason = job
+            .queued_reason
+            .as_ref()
+            .map(|reason| format!(" - {reason}"))
+            .unwrap_or_default();
+        println!(
+            "  {} {} {} {}{}",
+            job.id, job.status, job.priority, job.command, reason
+        );
+    }
+}
+
+fn print_doctor(report: &DoctorReport) {
+    println!("OS supported: {}", report.os_supported);
+    println!("OS: {}", report.os);
+    println!(
+        "Socket: {} ({})",
+        report.socket_path,
+        if report.socket_exists {
+            "present"
+        } else {
+            "missing"
+        }
+    );
+    println!(
+        "Database: {} ({})",
+        report.db_path,
+        if report.db_exists {
+            "present"
+        } else {
+            "missing"
+        }
+    );
+    println!("launchd plist: {}", report.launchd_plist_exists);
+    println!("Tool paths:");
+    if report.discovered_tools.is_empty() {
+        println!("  none");
+    }
+    for (tool, path) in &report.discovered_tools {
+        println!("  {tool}: {path}");
+    }
+}
+
+fn local_doctor(socket: &Path, db: &Path) -> anyhow::Result<DoctorReport> {
+    let discovered_tools = if db.exists() {
+        Store::open(db)?
+            .list_tool_paths()?
+            .into_iter()
+            .map(|tool| (tool.tool, tool.real_path))
+            .collect()
+    } else {
+        vec![]
+    };
+    let plist = std::env::var_os("HOME")
+        .map(PathBuf::from)
+        .unwrap_or_default()
+        .join("Library/LaunchAgents/dev.agentguard.agentguardd.plist");
+    Ok(DoctorReport {
+        os_supported: std::env::consts::OS == "macos",
+        os: format!("{} {}", std::env::consts::OS, std::env::consts::ARCH),
+        socket_path: socket.display().to_string(),
+        socket_exists: socket.exists(),
+        db_path: db.display().to_string(),
+        db_exists: db.exists(),
+        launchd_plist_exists: plist.exists(),
+        discovered_tools,
+    })
+}
+
+fn handle_unexpected<T>(response: Response) -> anyhow::Result<T> {
+    anyhow::bail!("unexpected daemon response: {response:?}")
+}
+
+fn shell_quote(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "'\\''"))
+}

package/crates/agentguard/src/bin/agentguardd.rs

@@ -0,0 +1,23 @@
+use agentguard_core::server::{DaemonConfig, default_db_path, default_socket_path, run_daemon};
+use clap::Parser;
+use std::path::PathBuf;
+
+#[derive(Debug, Parser)]
+#[command(name = "agentguardd", about = "AgentGuard user daemon")]
+struct Args {
+    #[arg(long, env = "AGENTGUARD_SOCKET")]
+    socket: Option<PathBuf>,
+    #[arg(long, env = "AGENTGUARD_DB")]
+    db: Option<PathBuf>,
+    #[arg(long)]
+    foreground: bool,
+}
+
+fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    run_daemon(DaemonConfig {
+        socket_path: args.socket.unwrap_or_else(default_socket_path),
+        db_path: args.db.unwrap_or_else(default_db_path),
+        foreground: args.foreground,
+    })
+}