Metadata-Version: 2.4
Name: nex-box
Version: 0.2.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Security
Summary: Sub-millisecond Copy-on-Write ephemeral sandbox runtime for autonomous coding agents.
Keywords: sandbox,agent,cow,reflink,testing,apfs,overlayfs
Author-email: The Trinity <nex@permanexus.org>
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# nex-box ⚡

**Sub-millisecond, zero-copy, kernel-level execution sandbox for autonomous coding agents.**

[![PyPI version](https://img.shields.io/pypi/v/nex-box.svg)](https://pypi.org/project/nex-box/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](https://pypi.org/project/nex-box/)
[![Rust](https://img.shields.io/badge/rust-2021%20edition-orange.svg)](https://www.rust-lang.org/)

`nex-box` solves the fundamental dilemma of autonomous AI engineering: **how to let coding agents run untrusted tests, builds, and destructive file mutations without risking host corruption or waiting seconds for Docker.**

Backed by macOS APFS `clonefile(2)`, Linux `ioctl(FICLONE)` copy-on-write primitives, and non-privileged `fuse-overlayfs` fallback, `nex-box` instantiates ephemeral scratch workspaces in **under 3 milliseconds**, traps all file mutations and network sockets at the kernel layer, and guarantees **instant atomic rollback on failure** or **zero-copy promotion on success**.

---

## Architectural Topology (v0.2.0 Hardened)

```
                  HOST WORKSPACE (Pristine Inode Root)
                                   │
              ┌────────────────────┴────────────────────┐
              │ clonefile(2) / ioctl(FICLONE) / Overlay │ < 2.5ms Latency
              ▼                                         ▼
   EPHEMERAL SCRATCH ROOT                    KERNEL CONFINEMENT ENCLAVE
   (.nexbox/sessions/box_xxx)                 ├── macOS Seatbelt: (deny network*)
              │                               └── Linux: unshare(CLONE_NEWNET)
              ├─────────────────────────────────────────┤
              │ COMMAND EXECUTION & WATCHDOG TIMER      │
              │ ├── Process Group Teardown (killpg)     │
              │ ├── Scratch Log I/O (Anti-Pipe Lock)    │
              │ └── Hard millisecond SIGKILL watchdog   │
              ├─────────────────────────────────────────┤
              │ STAT-INDEXED BLAKE3 SIMD ENGINE         │
              │ ├── Stat-gate (mtime + size filter)     │
              │ ├── Rayon parallel SIMD byte hash       │
              │ └── Extracts: Created, Modified, Deleted│
              └────────────────────┬────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
           EXIT CODE 0 & --commit        EXIT CODE != 0 / TIMEOUT
                    │                             │
                    ▼                             ▼
        [ATOMIC PROMOTION]               [AUTOMATIC ROLLBACK]
   Reflink changes to host tree.    Instant purge of scratch tree.
   Host updated in microseconds.    Host remains 100% untouched.
```

---

## What's New in v0.2.0

1. **Process Group Teardown (`killpg`)**:
   Watchdogs now isolate and disarm whole process groups (`setpgid(0, 0)` + `killpg(pgid, SIGKILL)`). Multiprocessing test harnesses, daemonized subprocesses, and background fork-bombs are killed immediately without orphaning zombie workers.
2. **OverlayFS Fallback for Linux ext4**:
   Auto-detects filesystems lacking native reflink support (e.g. ext4) and dynamically backs the scratch space using `fuse-overlayfs` or high-throughput parallel Rayon cloning. Dangerous shared hardlinks are completely eradicated.
3. **Cross-Volume Boundary Protection**:
   Strict `st_dev` invariant check ensures the workspace root and `.nexbox/` storage share the same physical filesystem partition, preventing silent fallback slowdowns or `EXDEV` link corruptions.
4. **Stat-Gated BLAKE3 SIMD Acceleration**:
   Files with matching byte size and nanosecond modification timestamps skip hash calculations, speeding up diff computation on large repositories ($\ge 10,000$ files) to single-digit microseconds.

---

## Installation

```bash
pip install nex-box
# or with uv:
uv pip install nex-box
```

Via Cargo:
```bash
cargo install nex-box
```

---

## Quickstart

### 1. Python API (`import nex_box`)

```python
import nex_box

outcome = nex_box.run(
    command=["pytest", "tests/"],
    commit=True,          # Automatically commit to host ONLY if exit code == 0
    timeout_ms=5000,      # Hard watchdog killpg after 5.0 seconds
    allow_net=False       # Kernel-level network socket isolation
)

if outcome.is_success():
    print(f"Verified in {outcome.duration_ms}ms (Strategy: {outcome.strategy})")
    print(f"Cloned in: {outcome.clone_duration_micros}µs")
    print(f"Files Modified: {outcome.diff.files_modified}")
else:
    print(f"Agent failed with exit code {outcome.exit_code}")
    print(outcome.stderr)
```

### 2. Standalone CLI (`nex-box`)

```bash
# Run untrusted commands in an ephemeral scratch sandbox
nex-box run -- bash -c "echo 'mutation' > test.txt && pytest"

# Atomic commit gated on exit code 0
nex-box run --commit -- python3 -m py_compile module.py

# Timeout enforcement with full process-group killpg
nex-box run --timeout-ms 2000 -- python3 -c "import time; time.sleep(10)"

# Air-gapped execution
nex-box run --allow-net false -- curl -I https://github.com
```

---

## License

Dual-licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
```

### File 4: src/lib.rs
```rust
//! src/lib.rs - Root library entrypoint exporting main components and PyO3 C-extension.

pub mod main_components;

#[cfg(feature = "python")]
use pyo3::prelude::*;

#[cfg(feature = "python")]
use main_components::python_bindings::{run, PySandboxOutcome, PyWorkspaceDiff};

/// Python native C-extension module entrypoint
#[cfg(feature = "python")]
#[pymodule]
fn nex_box(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(run, m)?)?;
    m.add_class::<PySandboxOutcome>()?;
    m.add_class::<PyWorkspaceDiff>()?;
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    Ok(())
}
```
