Thank you for your interest in contributing to Agent Hypervisor! This project provides runtime isolation, execution rings, and governance for autonomous AI agents. This guide will help you get set up and make your first contribution.
- Getting Started
- Development Setup
- Code Style
- Making Changes
- Testing
- Issue Guidelines
- Architecture Overview
- Design Philosophy
- Getting Help
# 1. Fork the repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/agent-hypervisor.git
cd agent-hypervisor
# 2. Add upstream remote
git remote add upstream https://github.com/imran-siddique/agent-hypervisor.git
# 3. Install in development mode
pip install -e ".[dev]"
# 4. Run tests to verify your setup
python -m pytest
# 5. Install pre-commit hooks
pip install pre-commit
pre-commit installThis project uses pre-commit to enforce code quality on every commit. The hooks include:
- Trailing whitespace and end-of-file fixes
- YAML validation and merge conflict detection
- Private key detection (security)
- Ruff linting and formatting
- mypy type checking (excludes tests)
- pytest check on push
Hooks are configured in .pre-commit-config.yaml. After installing with pre-commit install, they run automatically on git commit.
Agent Hypervisor requires Python 3.11 or higher and supports Python 3.11, 3.12, and 3.13. We recommend using pyenv to manage Python versions:
pyenv install 3.12
pyenv local 3.12Always use a virtual environment for development:
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
# Install all dev dependencies
pip install -e ".[dev]"Depending on what you're working on, install additional extras:
pip install -e ".[dev,api]" # FastAPI REST API server
pip install -e ".[dev,nexus]" # Structured logging (structlog)
pip install -e ".[dev,full]" # EverythingThe optional API layer is powered by FastAPI and Uvicorn:
pip install -e ".[api]"
uvicorn hypervisor.api.server:appBy default the server listens on http://127.0.0.1:8000. Add --reload during development for auto-restart on file changes.
- VS Code with the Python, Ruff, and mypy extensions
- PyCharm Professional with built-in type checking enabled
- Enable format-on-save with Ruff for consistent formatting
We use Ruff for linting and formatting, and mypy for type checking:
# Format code
ruff format src/ tests/
# Lint (with auto-fix)
ruff check src/ tests/ --fix
# Type check
mypy src/| Rule | Details |
|---|---|
| Line length | 100 characters maximum |
| Target version | Python 3.11 |
| Type hints | Required on all function signatures |
| Docstrings | Required for all public modules, classes, and functions |
| Docstring style | Google style |
| Import order | Enforced by Ruff (I rule) — stdlib → third-party → local |
| Lint rules | E, F, I, W, B, C4, UP |
All function signatures must include type hints. Use from __future__ import annotations for modern syntax:
from __future__ import annotations
from hypervisor.rings.engine import ExecutionRing
def assign_ring(
agent_did: str,
sigma_raw: float,
*,
session_id: str | None = None,
) -> ExecutionRing:
"""Assign an execution ring based on agent trust score.
Args:
agent_did: The DID identifier of the agent.
sigma_raw: The raw trust score (0.0–1.0).
session_id: Optional session to bind the assignment to.
Returns:
The execution ring assigned to the agent.
Raises:
ValueError: If sigma_raw is outside the valid range.
"""
...class SagaOrchestrator:
"""Orchestrates multi-step transactions with compensation.
Manages saga lifecycle including step execution, timeout
enforcement, retry with backoff, and reverse-order compensation
on failure.
Attributes:
session_id: The session this saga belongs to.
consistency_mode: Isolation level for saga execution.
Example:
>>> saga = orchestrator.create_saga(session_id="sess-1")
>>> step = orchestrator.add_step(
... saga.saga_id, "draft_email", "did:mesh:agent-1",
... execute_api="/api/draft", undo_api="/api/undo-draft",
... )
>>> result = await orchestrator.execute_step(saga.saga_id, step.step_id)
"""Create a branch from main using one of these prefixes:
| Prefix | Use For |
|---|---|
feat/ |
New features (e.g., feat/session-timeout) |
fix/ |
Bug fixes (e.g., fix/ring-escalation-bug) |
docs/ |
Documentation changes (e.g., docs/api-examples) |
test/ |
Test additions/improvements (e.g., test/kill-switch-edge-cases) |
refactor/ |
Code refactoring (e.g., refactor/saga-engine) |
chore/ |
Maintenance tasks (e.g., chore/update-deps) |
# Sync with upstream before branching
git fetch upstream
git checkout -b feat/my-feature upstream/mainWe follow Conventional Commits:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Types: feat, fix, docs, test, refactor, chore, ci, perf
Scopes (optional): session, rings, saga, liability, audit, security, api, observability
Examples:
feat(saga): add parallel execution with fan-out policies
fix(rings): correct ring privilege check for Ring-2
docs: update README with new install steps
test(liability): add slash cascade edge cases
perf(audit): optimize hash-chain delta computation
- Fork the repository and create your branch
- Make changes following the code style guidelines
- Write/update tests — all new features need test coverage
- Run the full check suite:
ruff format src/ tests/ ruff check src/ tests/ mypy src/ python -m pytest
- Push your branch and open a Pull Request against
main - Fill out the PR description with:
- What changed and why
- How to test the changes
- Which module is affected
- Related issue numbers (e.g.,
Closes #11)
- Address review feedback — maintainers may request changes
- Merge — a maintainer will merge once approved
PRs are evaluated on:
- Correctness and security implications
- Test coverage for new/changed behavior
- Type safety (mypy must pass with
--strict) - Documentation for public APIs
- Module independence (modules should work standalone)
# Run all tests
python -m pytest
# Run with verbose output
python -m pytest -v
# Run a specific test file
python -m pytest tests/test_kill_switch.py -v
# Run a specific test
python -m pytest tests/test_breach_detector.py::test_breach_triggers_demotion -v
# Unit tests only
python -m pytest tests/unit/ -v
# Integration tests only
python -m pytest tests/integration/ -v
# Run with coverage report
python -m pytest --cov=src/hypervisor --cov-report=html --cov-report=term-missing
# Run benchmarks
python benchmarks/bench_hypervisor.py- Test file location: Place tests in
tests/at the repo root; usetests/unit/for unit tests andtests/integration/for integration tests - Naming convention:
test_<module>.pyfor files,test_<behavior>for functions - Async tests: Use
pytest-asyncio— tests are auto-detected (asyncio_mode = "auto") - Property-based tests: Use Hypothesis for fuzzing
import pytest
from hypervisor.rings.engine import RingEngine, ExecutionRing
class TestRingEngine:
"""Tests for execution ring assignment logic."""
def test_high_trust_agent_gets_ring_2(self) -> None:
engine = RingEngine()
ring = engine.compute_ring(sigma_raw=0.85)
assert ring == ExecutionRing.RING_2_STANDARD
def test_untrusted_agent_gets_sandbox(self) -> None:
engine = RingEngine()
ring = engine.compute_ring(sigma_raw=0.30)
assert ring == ExecutionRing.RING_3_SANDBOX
@pytest.mark.asyncio
async def test_sudo_elevation_with_ttl(self) -> None:
engine = RingEngine()
elevated = await engine.elevate(
agent_did="did:mesh:agent-1",
target_ring=ExecutionRing.RING_1_PRIVILEGED,
ttl_seconds=60,
)
assert elevated.ring == ExecutionRing.RING_1_PRIVILEGED- Minimum coverage: 80% for new code
- Critical paths (rings, saga, security): aim for 90%+
- Run
python -m pytest --cov=src/hypervisor --cov-report=term-missingto identify uncovered lines
tests/
├── unit/ # Fast, isolated unit tests
├── integration/ # Cross-module integration tests
├── test_agent_manager.py # Agent lifecycle tests
├── test_breach_detector.py # Ring breach detection tests
├── test_classifier.py # Trust score classification tests
├── test_kill_switch.py # Kill switch & rate limiter tests
├── test_rate_limiter.py # Per-ring rate limiting tests
├── test_shapley_attribution.py # Fault attribution tests
└── __init__.py
When filing a bug, include:
- Agent Hypervisor version (
pip show agent-hypervisor) - Python version (
python --version) - Operating system
- Steps to reproduce — minimal code snippet or CLI commands
- Expected behavior vs. actual behavior
- Full error traceback if applicable
- Which module is affected (rings, saga, liability, etc.)
For feature requests, describe:
- Use case — what governance problem does this solve?
- Proposed solution — how should it work?
- Alternatives considered — what else did you look at?
- Which module should this belong to (or is it a new module)?
New to the project? Look for issues labeled:
| Label | Description |
|---|---|
good first issue |
Small, well-defined tasks for newcomers |
documentation |
Improve docs, examples, and guides |
help wanted |
Community contributions welcome |
agent-hypervisor/
├── src/hypervisor/ # Main package
│ ├── session/ # Shared Session Object lifecycle + VFS
│ ├── rings/ # 4-ring privilege model + elevation + breach detection
│ ├── saga/ # Saga orchestrator + fan-out + checkpoints + DSL
│ ├── liability/ # Sponsorship, penalty, attribution, quarantine, ledger
│ ├── audit/ # Delta engine, audit log, GC, commitment
│ ├── security/ # Rate limiter, kill switch
│ ├── observability/ # Event bus, causal trace IDs
│ ├── reversibility/ # Execute/Undo API registry
│ ├── verification/ # DID transaction history verification
│ ├── integrations/ # Nexus, Verification, IATP cross-module adapters
│ ├── api/ # FastAPI REST endpoints (22 endpoints)
│ ├── core.py # Core utilities and shared logic
│ ├── models.py # Pydantic models
│ └── providers.py # Dependency injection providers
├── tests/ # Test suite (457+ tests)
├── benchmarks/ # Performance benchmarks
├── examples/ # Working demos and dashboard
├── tutorials/ # Step-by-step tutorials
├── notebooks/ # Jupyter notebooks
└── docs/ # Documentation
| Module | Purpose | Key Abstractions |
|---|---|---|
| session | Session lifecycle, VFS namespacing, DID-bound identity | SharedSessionObject, SessionConfig, VFS |
| rings | 4-ring privilege levels, sudo elevation, breach detection | RingEngine, ExecutionRing, BreachDetector |
| saga | Multi-step transactions with compensation & fan-out | SagaOrchestrator, SagaStep, CompensationPolicy |
| liability | Sponsorship, penalty, fault attribution, quarantine | LiabilityEngine, VouchChain, SlashCascade |
| audit | Hash-chained delta trails, semantic diffs, GC | DeltaEngine, AuditLog, Commitment |
| security | Kill switch, per-ring rate limiting | KillSwitch, RateLimiter |
| observability | Structured event bus, causal trace IDs | EventBus, CausalTraceId |
| reversibility | Execute/undo API registry for saga steps | ReversibilityRegistry |
The privilege model is inspired by hardware CPU rings:
Ring 0 (Root) — Hypervisor config & penalty — requires SRE Witness
Ring 1 (Privileged) — Non-reversible actions — requires eff_score > 0.95 + consensus
Ring 2 (Standard) — Reversible actions — requires eff_score > 0.60
Ring 3 (Sandbox) — Read-only / research — default for unknown agents
Agents start in Ring 3 and earn promotion based on trust score. Ring breach detection triggers immediate demotion. Sudo elevation provides temporary privilege with TTL.
The saga orchestrator manages multi-step workflows:
- Timeout enforcement — steps that hang are automatically cancelled
- Retry with backoff — transient failures retry with exponential delay
- Reverse-order compensation — on failure, all committed steps are undone
- Escalation — if compensation fails, Joint Liability penalty is triggered
- Parallel execution — ALL_MUST_SUCCEED / MAJORITY / ANY policies
The security module provides runtime safety:
- Kill switch — graceful termination with saga step handoff to substitute agents
- Rate limiting — per-agent, per-ring limits (sandbox: 5 rps, root: 100 rps)
- Circuit breakers — automatic protection against cascading failures
"Isolation by Default" — Every agent session is isolated, every action is governed, every violation is attributable.
- Hardware-inspired privilege isolation (execution rings)
- Graduated trust, not binary allow/deny
- Automatic compensation for failed multi-step workflows
- Tamper-evident audit trails (hash-chained deltas)
- Runtime kill switch with graceful handoff
- Composability with Agent OS, Agent Mesh, and Agent SRE
- Implicit trust between agents
- Unaudited agent actions
- Static, binary access control
- Data loss on agent termination
- Monolithic design — modules should work standalone
- Questions? Open a Discussion
- Found a bug? Open an Issue
- Security issue? See SECURITY.md
By contributing, you agree that your contributions will be licensed under the MIT License.