Metadata-Version: 2.4
Name: vm-vmanager-agent
Version: 0.1.1
Summary: VManager per-host agent — the in-process device adapter (mgf-hrb-backed DeviceBackend) and, in later phases, the hypervisor/storage coordination the control plane drives. A consumer-app component (vmanager.agent), NOT an mgf.vm.* federation library.
Author-email: Bassam Alsanie <bassam@magogi.org>
License: MIT
Keywords: broker,device-passthrough,kvm,mgf-hrb,qemu,vfio
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Emulators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: mgf-common<0.53,>=0.51.0
Requires-Dist: mgf-hrb<0.2,>=0.1
Requires-Dist: mgf-vm-core<0.2,>=0.1
Provides-Extra: dev
Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# vm-vmanager-agent

VManager's per-host **agent** — the component that runs on each
hypervisor host and brokers hardware to the control plane.

Phase-0 ships the **device seam**: `vmanager.agent.device.HrbDeviceBackend`,
the [`mgf-hrb`](../mgf-hrb)-backed reference implementation of
`mgf.vm.core.contracts.DeviceBackend` (D-B4). It wraps the broker's
synchronous `Client` and is the broker half of device passthrough — the
broker mediates *who holds the device* (the lease); the hypervisor
adapter mediates the device's *presence in the guest*; the agent
coordinates the two as a transaction.

This is a **consumer-app component** under the PEP-420 `vmanager`
namespace (shared with `vm-vmanager-cli` and `vm-vmanager-gui`). It is
**not** an `mgf.vm.*` federation library. There is intentionally no
`src/vmanager/__init__.py`.

The agent's device adapter is **broker-only**: no `libvirt`, no
`grpc`/`protobuf`, no `mgf.vm.sdk.client`. An import-linter contract
makes that boundary a CI gate (it also breaks the
agent→sdk→libvirt→agent cycle).

## Authoritative design

The architecture, decisions, and roadmap live in
[**vm-vmanager-docs**](../vm-vmanager-docs). This README is a pointer;
the docs are the source of truth.

## Layout

```
src/vmanager/agent/        # the vmanager.agent package (PEP-420 namespace)
  device.py                # HrbDeviceBackend
tests/unit/                # broker-mocked unit tests (default; no broker)
tests/e2e/                 # CONF-D against a real mgf-hrb-server subprocess
```

## Development

```bash
uv sync --extra dev
uv run ruff check src tests
uv run mypy --strict src
uv run pytest --cov --cov-fail-under=80
uv run lint-imports
```

The end-to-end lane (`-m e2e`) spawns a real `mgf-hrb-server` per test;
it skips gracefully when the broker binary is not built.
