haon-agent 0.2.0__tar.gz

haon_agent-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: haon-agent
+Version: 0.2.0
+Summary: HAON PowerHub — miner agent: rent out idle GPU time on a decentralized compute marketplace.
+Author-email: HAON <alpha@haon.run>
+Maintainer-email: HAON <alpha@haon.run>
+License: MIT
+Project-URL: Homepage, https://staging.haon.run
+Project-URL: Documentation, https://staging.haon.run/docs/miner-install-quickstart.md
+Project-URL: Issues, https://github.com/caiorlm/HAON-PowerHub-Marketplace/issues
+Project-URL: Source, https://github.com/caiorlm/HAON-PowerHub-Marketplace/tree/main/apps/miner-agent
+Keywords: gpu,marketplace,distributed-computing,llm,ollama,comfyui,ai-infrastructure,miner-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: httpx<0.28,>=0.27
+Requires-Dist: websockets<14.0,>=13.0
+Requires-Dist: psutil<7.0,>=6.0
+Requires-Dist: keyring<26.0,>=25.0
+Requires-Dist: structlog<25.0,>=24.0
+Requires-Dist: pydantic<3.0,>=2.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+
+# haon-agent
+
+The miner-side agent for the **HAON PowerHub** distributed GPU marketplace.
+Run this on a machine with a GPU, register with the marketplace, and
+earn credit every time a worker rents your compute time.
+
+- **Website**: <https://staging.haon.run>
+- **Quickstart**: <https://staging.haon.run/docs/miner-install-quickstart.md>
+- **Supported OS**: macOS, Linux, Windows 10+ (Python 3.11+)
+
+---
+
+## One-command install
+
+### macOS / Linux
+```bash
+curl -sSL https://staging.haon.run/install-miner.sh | bash
+```
+
+### Windows (PowerShell)
+```powershell
+iwr -useb https://staging.haon.run/install-miner.ps1 | iex
+```
+
+Either one-liner installs this package into a per-user venv at
+`~/.haon/venv` (no admin required), exposes the `haon-agent` CLI, and
+launches the pairing wizard.
+
+---
+
+## Manual install (prefer the one-liner for non-developers)
+
+```bash
+pip install haon-agent
+haon-agent pair         # email + password → marketplace registration
+haon-agent run          # starts the agent, heartbeats begin
+```
+
+Configuration lands in `~/.haon/agent.toml`; the API key is stored in
+your OS keyring (with a 0600 file fallback).
+
+---
+
+## What the agent does
+
+- Probes your hardware (CPU / RAM / GPU via `nvidia-smi`).
+- Registers the machine with the HAON API and mints a scoped API key.
+- Holds a WebSocket to the HAON broker (outbound, NAT-friendly).
+- When a worker opens a session against your machine, the agent pairs
+  the tunnel + starts the requested runtime container (Ollama, ComfyUI,
+  custom HTTP).
+- Emits usage ticks every 10 seconds; the server turns ticks into
+  earnings in your wallet.
+
+Nothing the agent does touches ports on your side — all traffic is
+outbound WebSocket over TLS to `broker.staging.haon.run`. You can run it
+behind NAT, corporate firewalls, or whatever.
+
+---
+
+## Supported runtimes (alpha)
+
+| Runtime | Status | Notes |
+|---|---|---|
+| `echo` | ✅ Works everywhere | CPU-only smoke test |
+| `ollama` | 🚧 Docker-based (today) / native (next) | LLM inference |
+| `comfyui` | 🚧 Docker-based | Image / video diffusion |
+| `custom_http` | 🚧 Docker-based | Bring your own HTTP server |
+
+Docker-based runtimes require Docker Desktop (Windows/macOS) or
+Docker Engine (Linux) + the NVIDIA Container Toolkit if you want GPU
+passthrough. The pairing wizard does not yet auto-install Docker — do
+that step yourself before running compute-heavy runtimes.
+
+---
+
+## Uninstall
+
+Everything the installer writes lives under `~/.haon`:
+
+```bash
+haon-agent logout       # clears credentials from the keyring
+rm -rf ~/.haon          # removes the venv + config
+```
+
+No registry edits on Windows, no systemd unit on Linux.
+
+---
+
+## Security + privacy posture
+
+- All API traffic is TLS 1.2+. Self-signed certs are rejected.
+- Refresh tokens are rotated on every use (single-use).
+- The agent never executes arbitrary code from workers — runtimes are
+  explicit runtime containers you opt into.
+- No telemetry beyond the heartbeats + usage ticks that the marketplace
+  needs for billing. Source is auditable — this package is published
+  from the same git history as the server.
+
+Report security issues to `alpha@haon.run`.
+
+---
+
+## License
+
+MIT. See `LICENSE` in the source repository.

haon_agent-0.2.0/README.md

@@ -0,0 +1,106 @@
+# haon-agent
+
+The miner-side agent for the **HAON PowerHub** distributed GPU marketplace.
+Run this on a machine with a GPU, register with the marketplace, and
+earn credit every time a worker rents your compute time.
+
+- **Website**: <https://staging.haon.run>
+- **Quickstart**: <https://staging.haon.run/docs/miner-install-quickstart.md>
+- **Supported OS**: macOS, Linux, Windows 10+ (Python 3.11+)
+
+---
+
+## One-command install
+
+### macOS / Linux
+```bash
+curl -sSL https://staging.haon.run/install-miner.sh | bash
+```
+
+### Windows (PowerShell)
+```powershell
+iwr -useb https://staging.haon.run/install-miner.ps1 | iex
+```
+
+Either one-liner installs this package into a per-user venv at
+`~/.haon/venv` (no admin required), exposes the `haon-agent` CLI, and
+launches the pairing wizard.
+
+---
+
+## Manual install (prefer the one-liner for non-developers)
+
+```bash
+pip install haon-agent
+haon-agent pair         # email + password → marketplace registration
+haon-agent run          # starts the agent, heartbeats begin
+```
+
+Configuration lands in `~/.haon/agent.toml`; the API key is stored in
+your OS keyring (with a 0600 file fallback).
+
+---
+
+## What the agent does
+
+- Probes your hardware (CPU / RAM / GPU via `nvidia-smi`).
+- Registers the machine with the HAON API and mints a scoped API key.
+- Holds a WebSocket to the HAON broker (outbound, NAT-friendly).
+- When a worker opens a session against your machine, the agent pairs
+  the tunnel + starts the requested runtime container (Ollama, ComfyUI,
+  custom HTTP).
+- Emits usage ticks every 10 seconds; the server turns ticks into
+  earnings in your wallet.
+
+Nothing the agent does touches ports on your side — all traffic is
+outbound WebSocket over TLS to `broker.staging.haon.run`. You can run it
+behind NAT, corporate firewalls, or whatever.
+
+---
+
+## Supported runtimes (alpha)
+
+| Runtime | Status | Notes |
+|---|---|---|
+| `echo` | ✅ Works everywhere | CPU-only smoke test |
+| `ollama` | 🚧 Docker-based (today) / native (next) | LLM inference |
+| `comfyui` | 🚧 Docker-based | Image / video diffusion |
+| `custom_http` | 🚧 Docker-based | Bring your own HTTP server |
+
+Docker-based runtimes require Docker Desktop (Windows/macOS) or
+Docker Engine (Linux) + the NVIDIA Container Toolkit if you want GPU
+passthrough. The pairing wizard does not yet auto-install Docker — do
+that step yourself before running compute-heavy runtimes.
+
+---
+
+## Uninstall
+
+Everything the installer writes lives under `~/.haon`:
+
+```bash
+haon-agent logout       # clears credentials from the keyring
+rm -rf ~/.haon          # removes the venv + config
+```
+
+No registry edits on Windows, no systemd unit on Linux.
+
+---
+
+## Security + privacy posture
+
+- All API traffic is TLS 1.2+. Self-signed certs are rejected.
+- Refresh tokens are rotated on every use (single-use).
+- The agent never executes arbitrary code from workers — runtimes are
+  explicit runtime containers you opt into.
+- No telemetry beyond the heartbeats + usage ticks that the marketplace
+  needs for billing. Source is auditable — this package is published
+  from the same git history as the server.
+
+Report security issues to `alpha@haon.run`.
+
+---
+
+## License
+
+MIT. See `LICENSE` in the source repository.

haon_agent-0.2.0/haon_agent/__init__.py

@@ -0,0 +1,3 @@
+"""HAON PowerHub — Miner Agent."""
+
+__version__ = "0.2.0"

haon_agent-0.2.0/haon_agent/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m haon_agent`."""
+
+from haon_agent.cli import cli
+
+if __name__ == "__main__":
+    cli()

haon_agent-0.2.0/haon_agent/agent.py

@@ -0,0 +1,233 @@
+"""The agent's main orchestrator loop.
+
+    heartbeat (every N seconds)
+      │
+      ├── if heartbeat.session_accepted_ids non-empty:
+      │     for each session_id:
+      │       accept_session(session_id)
+      │
+      └── sleep(heartbeat_interval)
+
+    accept_session(session_id):
+      call POST /v1/sessions/{id}/start → handoff
+      connect to broker with handoff.tunnel_token
+      wait for PAIRED
+      spawn runtime
+      concurrently:
+        - forward worker DATA frames to runtime.push
+        - forward runtime output to broker.send_data
+      on CLOSE / UNPAIRED / runtime stop: tear everything down, POST /close.
+
+Recovery:
+    If heartbeat fails we keep retrying with exponential backoff. If broker
+    disconnects mid-session we close the session via API. No silent failures.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+import structlog
+
+from haon_agent.api_client import ApiClient, ApiError, SessionHandoff
+from haon_agent.broker_client import BrokerClient, FrameType
+from haon_agent.config import AgentConfig
+from haon_agent.runtime import get_runtime
+from haon_agent.runtime.base import Runtime
+
+log = structlog.get_logger("agent")
+
+
+@dataclass
+class AgentDeps:
+    api: ApiClient
+    config: AgentConfig
+    # Factory so tests can inject a fake BrokerClient.
+    broker_factory: Callable[[str, str], BrokerClient] = lambda url, token: BrokerClient(url, token)
+    # Runtime resolver (defaults to the module-level registry).
+    runtime_factory: Callable[[str], Runtime] = get_runtime
+
+
+class Agent:
+    def __init__(self, deps: AgentDeps) -> None:
+        self._deps = deps
+        self._running = False
+        self._active_sessions: dict[str, asyncio.Task[None]] = {}
+        self._stop_event = asyncio.Event()
+
+    async def run(self) -> None:
+        self._running = True
+        log.info("agent_starting", api_url=self._deps.config.api_url)
+        try:
+            await self._main_loop()
+        finally:
+            self._running = False
+            # Cancel any active session tasks.
+            for sid, task in list(self._active_sessions.items()):
+                log.info("session_task_cancelling", session_id=sid)
+                task.cancel()
+            for task in list(self._active_sessions.values()):
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+            log.info("agent_stopped")
+
+    def request_stop(self) -> None:
+        self._stop_event.set()
+
+    async def _main_loop(self) -> None:
+        cfg = self._deps.config
+        if not cfg.machine_id:
+            raise RuntimeError("machine_id not configured; run `haon-agent register` first")
+
+        backoff = 1.0
+        while not self._stop_event.is_set():
+            try:
+                resp = await self._deps.api.heartbeat(
+                    cfg.machine_id,
+                    runtime_ready=True,
+                    pending_sessions=len(self._active_sessions),
+                )
+                backoff = 1.0  # reset on success
+                offered = resp.get("session_accepted_ids") or []
+                for sid in offered:
+                    if sid in self._active_sessions:
+                        continue
+                    log.info("session_offered_received", session_id=sid)
+                    task = asyncio.create_task(self._run_session(sid))
+                    self._active_sessions[sid] = task
+                    # Purge completed tasks.
+                    for done_sid in [
+                        s for s, t in self._active_sessions.items() if t.done()
+                    ]:
+                        self._active_sessions.pop(done_sid, None)
+            except ApiError as e:
+                log.warning(
+                    "heartbeat_failed",
+                    code=e.code,
+                    status_code=e.status_code,
+                )
+            except Exception as e:  # noqa: BLE001
+                log.exception("heartbeat_unhandled_error", error=str(e))
+                backoff = min(backoff * 2, 30.0)
+
+            try:
+                await asyncio.wait_for(
+                    self._stop_event.wait(),
+                    timeout=cfg.heartbeat_interval_seconds if backoff <= 1.0 else backoff,
+                )
+            except asyncio.TimeoutError:
+                pass
+
+    # ── Per-session pipeline ────────────────────────────────────────────
+
+    async def _run_session(self, session_id: str) -> None:
+        try:
+            handoff = await self._deps.api.start_session(session_id)
+        except ApiError as e:
+            log.warning(
+                "session_start_rejected",
+                session_id=session_id,
+                code=e.code,
+            )
+            return
+
+        runtime_name = handoff.runtime or self._deps.config.default_runtime
+        try:
+            runtime = self._deps.runtime_factory(runtime_name)
+        except KeyError:
+            log.warning(
+                "runtime_unsupported",
+                session_id=session_id,
+                runtime=runtime_name,
+            )
+            await self._safe_close(session_id, reason="miner_closed")
+            return
+
+        broker = self._deps.broker_factory(
+            handoff.tunnel_broker_url, handoff.tunnel_token
+        )
+        close_reason = "miner_closed"
+        tick_emitter = None
+        try:
+            await broker.connect()
+            # Wait for PAIRED — the worker-client opens the other side of the tunnel.
+            paired_task = asyncio.create_task(broker.await_paired(timeout=15))
+
+            async def on_runtime_output(data: bytes) -> None:
+                await broker.send_data(data)
+
+            await runtime.start(on_runtime_output)
+            await paired_task
+
+            log.info("session_paired_and_running", session_id=session_id)
+
+            # Phase 12: start the tick emitter for this session.
+            from haon_agent.tick_emitter import TickEmitter
+
+            container_name = None
+            handle = getattr(runtime, "_handle", None)
+            if handle is not None:
+                container_name = getattr(handle, "container_name", None)
+            tick_emitter = TickEmitter(
+                api=self._deps.api,
+                session_id=session_id,
+                broker=broker,
+                container_name=container_name,
+            )
+            tick_emitter.start()
+
+            async for ev in broker.events():
+                if ev.type is FrameType.DATA:
+                    await runtime.push(ev.payload)
+                elif ev.type is FrameType.UNPAIRED:
+                    log.warning("session_unpaired", session_id=session_id)
+                    # Worker dropped — Phase 10 treats it as session end.
+                    # A reconnection-grace window can land later.
+                    break
+                elif ev.type is FrameType.CLOSE:
+                    log.info(
+                        "session_broker_closed",
+                        session_id=session_id,
+                        payload=ev.json(),
+                    )
+                    break
+                elif ev.type is FrameType.ERROR:
+                    log.error(
+                        "session_broker_error",
+                        session_id=session_id,
+                        payload=ev.json(),
+                    )
+                    break
+        except Exception as e:  # noqa: BLE001
+            log.exception(
+                "session_pipeline_error", session_id=session_id, error=str(e)
+            )
+            close_reason = "miner_closed"
+        finally:
+            if tick_emitter is not None:
+                try:
+                    await tick_emitter.stop()
+                except Exception:  # noqa: BLE001
+                    pass
+            try:
+                await runtime.stop()
+            except Exception:  # noqa: BLE001
+                pass
+            await broker.close()
+            await self._safe_close(session_id, reason=close_reason)
+            self._active_sessions.pop(session_id, None)
+
+    async def _safe_close(self, session_id: str, *, reason: str) -> None:
+        try:
+            await self._deps.api.close_session(session_id, reason=reason)
+        except ApiError as e:
+            log.warning(
+                "session_close_failed", session_id=session_id, code=e.code
+            )
+        except Exception as e:  # noqa: BLE001
+            log.warning(
+                "session_close_unhandled", session_id=session_id, error=str(e)
+            )

haon_agent-0.2.0/haon_agent/api_client.py

@@ -0,0 +1,182 @@
+"""Thin HAON API client used by the agent.
+
+One class, one responsibility per method. In tests we swap `httpx`'s transport
+for an `ASGITransport` pointed at an in-process FastAPI app — no network, no
+mocks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class ApiError(Exception):
+    def __init__(self, status_code: int, code: str, message: str, details: dict | None = None) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+
+def _raise_for_error(r: httpx.Response) -> None:
+    if r.is_success:
+        return
+    try:
+        body = r.json()
+        err = body.get("error", {})
+        code = err.get("code", "UNKNOWN")
+        message = err.get("message", r.text)
+        details = err.get("details", {})
+    except Exception:  # noqa: BLE001
+        code = "HTTP_ERROR"
+        message = r.text
+        details = {}
+    raise ApiError(r.status_code, code, message, details)
+
+
+@dataclass
+class SessionHandoff:
+    """What the agent needs to actually run a session."""
+    session_id: str
+    worker_id: str
+    machine_id: str
+    runtime: str
+    tunnel_broker_url: str
+    tunnel_token: str
+    expires_at: str
+
+
+class ApiClient:
+    """Token-auth HTTP client for the HAON API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            transport=transport,
+            timeout=timeout,
+            headers={"X-API-Key": api_key, "User-Agent": "haon-agent/0.2"},
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "ApiClient":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self._client.aclose()
+
+    # ── Machines ────────────────────────────────────────────────────────
+
+    async def register_machine(
+        self,
+        *,
+        hub_id: str,
+        name: str,
+        cpu_model: str,
+        cpu_cores: int,
+        ram_gb: int,
+        gpu_model: str | None,
+        gpu_vram_gb: int | None,
+        gpu_count: int,
+        supported_runtimes: list[str],
+        hardware_fingerprint: str,
+        hardware_signature: str | None = None,
+    ) -> dict:
+        payload = {
+            "hub_id": hub_id,
+            "name": name,
+            "cpu_model": cpu_model,
+            "cpu_cores": cpu_cores,
+            "ram_gb": ram_gb,
+            "gpu_count": gpu_count,
+            "supported_runtimes": supported_runtimes,
+            "hardware_fingerprint": hardware_fingerprint,
+        }
+        if gpu_model is not None:
+            payload["gpu_model"] = gpu_model
+        if gpu_vram_gb is not None:
+            payload["gpu_vram_gb"] = gpu_vram_gb
+        if hardware_signature is not None:
+            payload["hardware_signature"] = hardware_signature
+
+        # Agent needs a user JWT (not API key) to register a machine. In Phase 10
+        # registration happens via `haon-agent register` which prompts for
+        # email+password → JWT → register. The runtime agent uses API keys.
+        # For now the method exists as a convenience; the CLI uses the login flow.
+        r = await self._client.post("/v1/machines", json=payload)
+        _raise_for_error(r)
+        return r.json()
+
+    async def heartbeat(
+        self,
+        machine_id: str,
+        *,
+        runtime_ready: bool,
+        cpu_percent: float | None = None,
+        ram_used_mb: int | None = None,
+        gpu_utilization_percent: list[float] | None = None,
+        pending_sessions: int | None = None,
+    ) -> dict:
+        payload: dict = {"runtime_ready": runtime_ready}
+        if cpu_percent is not None:
+            payload["cpu_percent"] = cpu_percent
+        if ram_used_mb is not None:
+            payload["ram_used_mb"] = ram_used_mb
+        if gpu_utilization_percent is not None:
+            payload["gpu_utilization_percent"] = gpu_utilization_percent
+        if pending_sessions is not None:
+            payload["pending_sessions"] = pending_sessions
+        r = await self._client.post(
+            f"/v1/machines/{machine_id}/heartbeat", json=payload
+        )
+        _raise_for_error(r)
+        return r.json()
+
+    # ── Sessions ────────────────────────────────────────────────────────
+
+    async def start_session(self, session_id: str) -> SessionHandoff:
+        r = await self._client.post(f"/v1/sessions/{session_id}/start")
+        _raise_for_error(r)
+        body = r.json()
+        sess = body["session"]
+        return SessionHandoff(
+            session_id=sess["id"],
+            worker_id=sess["worker_id"],
+            machine_id=sess["machine_id"],
+            runtime=sess.get("runtime") or "",
+            tunnel_broker_url=body["tunnel"]["broker_url"],
+            tunnel_token=body["tunnel"]["token"],
+            expires_at=body["tunnel"]["expires_at"],
+        )
+
+    async def close_session(self, session_id: str, reason: str = "miner_closed") -> dict:
+        r = await self._client.post(
+            f"/v1/sessions/{session_id}/close", json={"reason": reason}
+        )
+        _raise_for_error(r)
+        return r.json()
+
+    async def get_session(self, session_id: str) -> dict:
+        r = await self._client.get(f"/v1/sessions/{session_id}")
+        _raise_for_error(r)
+        return r.json()
+
+    # ── Usage ticks ─────────────────────────────────────────────────────
+
+    async def post_ticks(self, ticks: list[dict]) -> dict:
+        """Submit a batch (1..10) of UsageTick records."""
+        r = await self._client.post("/v1/usage/ticks", json={"ticks": ticks})
+        _raise_for_error(r)
+        return r.json()