agentguard-local 0.1.0

package/docs/DECISIONS.md

@@ -0,0 +1,37 @@
+# AgentGuard Decisions
+
+## D1: Preserve Terminal I/O With A Client-Side Runner
+
+Original LLD choice: use a client-side shim plus daemon instead of routing interactive sessions through a daemon-owned PTY.
+
+Observed constraint: preserving stdin/stdout/stderr/cwd/env and exit code is essential for CLI tools and test fixtures.
+
+Chosen adjustment: `agentguard run` asks the daemon for admission, then the client process spawns the real tool in a new process group with inherited stdio. The daemon records root pid/pgid and manages only that guarded process group.
+
+Tradeoff: the daemon does not own the child process directly, so exit registration is cooperative. Daemon restart reconciliation handles still-running pids and marks uncertain records `lost`.
+
+Tests: `run_fake_tool_records_job_and_preserves_stdio_and_exit_code`, `daemon_restart_reconciles_still_running_job`, and `shim_wraps_fake_codex_without_real_codex_and_injects_thread_cap`.
+
+## D2: Use A Command-Output Memory Sampler Fallback In MVP
+
+Original LLD choice: prefer DispatchSource memory pressure events, `host_statistics64` / `vm_statistics64`, `ProcessInfo.physicalMemory`, and pid/process APIs behind traits.
+
+Observed constraint: implementing and binding the low-level macOS APIs would slow the MVP without changing the pure scheduler and policy behavior.
+
+Chosen adjustment: keep pressure sampling at the daemon edge and use stable macOS command output from `sysctl hw.memsize` and `vm_stat` as the fallback sampler. Deterministic pressure tests use `AGENTGUARD_FAKE_PRESSURE_FILE`.
+
+Tradeoff: this fallback is polling-oriented and less precise than DispatchSource pressure callbacks. The core pressure classifier and scheduler remain pure so native API sampling can replace the fallback later.
+
+Tests: `pressure_classifier_uses_thresholds_and_events`, `pressure_recovery_hysteresis_requires_stable_recovery`, `simulated_soft_pressure_queues_then_recovery_admits_job`, and `simulated_critical_pressure_pauses_and_recovery_resumes_guarded_group`.
+
+## D3: Codex Integration Is Preventive In V1
+
+Original LLD choice: inject a safe subagent/thread cap with `-c agents.max_threads=N` unless the user supplied an explicit override.
+
+Observed constraint: an external local daemon cannot reliably queue individual Codex subagents inside an already-running Codex session.
+
+Chosen adjustment: the Codex adapter only rewrites launch arguments. It prepends `-c agents.max_threads=N` when no explicit `agents.max_threads` setting is present.
+
+Tradeoff: AgentGuard controls initial Codex fan-out but does not inspect or schedule individual subagents after launch.
+
+Tests: `codex_adapter_injects_thread_cap_when_absent`, `codex_adapter_does_not_override_explicit_config`, and `shim_wraps_fake_codex_without_real_codex_and_injects_thread_cap`.

package/docs/TESTING.md

@@ -0,0 +1,75 @@
+# AgentGuard Testing
+
+Run the required checks from the repository root:
+
+```sh
+cargo fmt --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features
+```
+
+If `cargo nextest` is installed, also run:
+
+```sh
+cargo nextest run --workspace --all-features
+```
+
+Do not install nextest just for this project.
+
+## Fake Pressure Testing
+
+The daemon supports deterministic pressure tests through `AGENTGUARD_FAKE_PRESSURE_FILE` when `AGENTGUARD_TEST_MODE=1` is set:
+
+```sh
+printf normal > /tmp/agentguard-pressure.txt
+AGENTGUARD_TEST_MODE=1 \
+AGENTGUARD_FAKE_PRESSURE_FILE=/tmp/agentguard-pressure.txt \
+target/debug/agentguardd --socket /tmp/agentguard.sock --db /tmp/agentguard.db --foreground
+```
+
+Change the file to `soft` to force queued admission and `critical` to force guarded process-group pause behavior:
+
+```sh
+printf soft > /tmp/agentguard-pressure.txt
+printf critical > /tmp/agentguard-pressure.txt
+printf normal > /tmp/agentguard-pressure.txt
+```
+
+The integration tests use this path rather than allocating large memory, which keeps smoke tests safe on 8GB Macs.
+
+## Coverage Map
+
+- Unit: pressure classifier threshold behavior.
+- Unit: pressure recovery hysteresis.
+- Unit: scheduler admission under normal pressure.
+- Unit: scheduler queueing under soft pressure.
+- Unit: scheduler pause selection under critical pressure.
+- Unit: priority ordering plus aging.
+- Unit: policy load/save/defaults.
+- Unit: job lifecycle transition validity.
+- Unit: Codex adapter injects `agents.max_threads` when absent.
+- Unit: Codex adapter does not override explicit user config.
+- Unit: socket protocol serialization compatibility.
+- Integration: start daemon on a temporary socket and SQLite database.
+- Integration: `agentguard status --json` returns pressure, policy, and job state.
+- Integration: `agentguard run -- <fake-tool>` starts and records a job.
+- Integration: active job limit queues the second job.
+- Integration: simulated soft pressure queues a job with a human-readable reason.
+- Integration: simulated recovery admits queued jobs.
+- Integration: simulated critical pressure pauses a low-priority guarded process group.
+- Integration: resume after recovery sends `SIGCONT` to the guarded process group.
+- Integration: daemon restart reconciles a still-running job.
+- Integration: shim preserves cwd/env/args/stdout/stderr/stdin behavior and exit code through inherited process execution.
+- Integration: shim dispatch wraps a fake `codex` binary without requiring real Codex.
+
+## macOS Smoke Checks
+
+These are safe manual checks after `cargo build`:
+
+```sh
+target/debug/agentguard doctor
+target/debug/agentguard run -- /bin/sleep 1
+target/debug/agentguard run --priority low -- /bin/sleep 30
+```
+
+Use fake pressure for pressure scenarios. Do not allocate large memory on small Macs just to exercise queueing or pause behavior.

package/npm/bin/agentguard

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+BIN="$DIR/darwin-arm64/agentguard"
+if [ ! -x "$BIN" ]; then
+  echo "agentguard: bundled darwin-arm64 binary is missing. Build from source with cargo build --release." >&2
+  exit 127
+fi
+exec "$BIN" "$@"

package/npm/bin/agentguardd

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+BIN="$DIR/darwin-arm64/agentguardd"
+if [ ! -x "$BIN" ]; then
+  echo "agentguardd: bundled darwin-arm64 binary is missing. Build from source with cargo build --release." >&2
+  exit 127
+fi
+exec "$BIN" "$@"

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agentguard-local",
+  "version": "0.1.0",
+  "description": "macOS-first RAM-aware admission controller for local AI coding CLI processes",
+  "license": "MIT OR Apache-2.0",
+  "homepage": "https://github.com/aiswarya797/agentguard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiswarya797/agentguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aiswarya797/agentguard/issues"
+  },
+  "keywords": [
+    "agentguard",
+    "codex",
+    "macos",
+    "cli",
+    "memory",
+    "scheduler"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "bin": {
+    "agentguard": "npm/bin/agentguard",
+    "agentguardd": "npm/bin/agentguardd"
+  },
+  "files": [
+    "Cargo.lock",
+    "Cargo.toml",
+    "README.md",
+    "crates/",
+    "docs/DECISIONS.md",
+    "docs/TESTING.md",
+    "npm/bin/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}