hud-python 0.4.36__py3-none-any.whl → 0.4.37__py3-none-any.whl

hud/cli/rl/wait_utils.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import select
+import sys
+import threading
+import time as _time
+from typing import TYPE_CHECKING
+
+from watchfiles import watch
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def wait_for_enter_cancel_or_change(file_path: Path) -> tuple[bool, bool, bool]:
+    """Block until Enter (start), 'q' (cancel), or file change.
+
+    Returns (start_training, cancelled, changed).
+    - start_training: True if Enter (or any non-'q' line on POSIX) was received
+    - cancelled: True if 'q' was received or Ctrl-C
+    - changed: True if the file changed on disk
+    """
+    start_training = False
+    cancelled = False
+    changed = False
+
+    stop_evt: threading.Event = threading.Event()
+    changed_evt: threading.Event = threading.Event()
+
+    def _watcher() -> None:
+        with contextlib.suppress(Exception):
+            for _ in watch(file_path, stop_event=stop_evt, debounce=200):
+                changed_evt.set()
+                break
+
+    t = threading.Thread(target=_watcher, daemon=True)
+    t.start()
+
+    try:
+        if os.name == "nt":
+            import msvcrt  # type: ignore[attr-defined]
+
+            while True:
+                if changed_evt.is_set():
+                    changed = True
+                    break
+
+                if msvcrt.kbhit():
+                    ch = msvcrt.getwch()
+                    if ch in ("\r", "\n"):
+                        start_training = True
+                        break
+                    if ch.lower() == "q":
+                        cancelled = True
+                        break
+                _time.sleep(0.15)
+        else:
+            while True:
+                if changed_evt.is_set():
+                    changed = True
+                    break
+
+                rlist, _, _ = select.select([sys.stdin], [], [], 0.25)
+                if rlist:
+                    line = sys.stdin.readline()
+                    if line is None:
+                        continue
+                    stripped = line.strip().lower()
+                    if stripped == "q":
+                        cancelled = True
+                        break
+                    # Any other (including empty) => start
+                    start_training = True
+                    break
+                _time.sleep(0.05)
+
+    except KeyboardInterrupt:
+        cancelled = True
+    finally:
+        stop_evt.set()
+        with contextlib.suppress(Exception):
+            t.join(timeout=1)
+
+    return start_training, cancelled, changed
+
+
+__all__ = ["wait_for_enter_cancel_or_change"]

hud/cli/utils/env_check.py

@@ -0,0 +1,196 @@
+"""Environment build checks and discovery helpers.
+
+Shared utilities to:
+- locate an environment directory related to a tasks file
+- ensure the environment is built and up-to-date via source hash comparison
+"""
+
+from __future__ import annotations
+
+import contextlib
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+
+from hud.utils.hud_console import hud_console
+
+from .docker import require_docker_running
+from .source_hash import compute_source_hash, list_source_files
+
+
+def _parse_generated_at(lock_data: dict[str, Any]) -> float | None:
+    """Parse build.generatedAt into a POSIX timestamp (seconds).
+
+    Returns None if missing or unparsable.
+    """
+    try:
+        generated_at = (lock_data.get("build") or {}).get("generatedAt")
+        if not isinstance(generated_at, str):
+            return None
+        # Support ...Z and offsets
+        iso = generated_at.replace("Z", "+00:00")
+        dt = datetime.fromisoformat(iso)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=UTC)
+        return dt.timestamp()
+    except Exception:
+        return None
+
+
+def _collect_source_diffs(env_dir: Path, lock_data: dict[str, Any]) -> dict[str, list[str]]:
+    """Compute added/removed/modified files since last build using names + mtimes.
+
+    - added/removed are based on the stored build.sourceFiles list vs current file list
+    - modified is based on mtime newer than build.generatedAt for files present now
+    """
+    try:
+        stored_files = (
+            (lock_data.get("build") or {}).get("sourceFiles") if isinstance(lock_data, dict) else []
+        )
+        stored_set = set(str(p) for p in (stored_files or []))
+    except Exception:
+        stored_set = set()
+
+    current_paths = list_source_files(env_dir)
+    # Normalize to POSIX-style relative strings
+    current_list = [str(p.resolve().relative_to(env_dir)).replace("\\", "/") for p in current_paths]
+    current_set = set(current_list)
+
+    added = sorted(current_set - stored_set)
+    removed = sorted(stored_set - current_set)
+
+    # Modified: mtime newer than build.generatedAt
+    modified: list[str] = []
+    built_ts = _parse_generated_at(lock_data)
+    if built_ts is not None:
+        for rel in sorted(current_set & (stored_set or current_set)):
+            with contextlib.suppress(Exception):
+                p = env_dir / rel
+                if p.exists() and p.stat().st_mtime > built_ts:
+                    modified.append(rel)
+
+    return {"added": added, "removed": removed, "modified": modified}
+
+
+def find_environment_dir(tasks_path: Path) -> Path | None:
+    """Best-effort discovery of a nearby environment directory.
+
+    Preference order:
+    - directory with hud.lock.yaml
+    - directory that looks like an environment (Dockerfile + pyproject.toml)
+    - searches tasks dir, CWD, and a couple of parents
+    """
+    from .environment import is_environment_directory  # local import to avoid cycles
+
+    candidates: list[Path] = []
+    cwd = Path.cwd()
+    candidates.extend([tasks_path.parent, cwd])
+
+    # Add parents (up to 2 levels for each)
+    for base in list(candidates):
+        p = base
+        for _ in range(2):
+            p = p.parent
+            if p not in candidates:
+                candidates.append(p)
+
+    # Prefer those with hud.lock.yaml
+    for d in candidates:
+        if (d / "hud.lock.yaml").exists():
+            return d
+
+    # Otherwise, find a plausible environment dir
+    for d in candidates:
+        try:
+            if is_environment_directory(d):
+                return d
+        except Exception as e:
+            hud_console.debug(f"Skipping path {d}: {e}")
+            continue
+
+    return None
+
+
+def ensure_built(env_dir: Path, *, interactive: bool = True) -> dict[str, Any]:
+    """Ensure env has a lock and matches current sources via source hash.
+
+    If interactive is True, prompts to build/rebuild as needed. If False, only warns.
+    Returns the loaded lock data (empty dict if unreadable/missing).
+    """
+    from hud.cli.build import build_environment  # local import to avoid import cycles
+
+    lock_path = env_dir / "hud.lock.yaml"
+    if not lock_path.exists():
+        if interactive:
+            hud_console.warning("No hud.lock.yaml found. The environment hasn't been built.")
+            ok = hud_console.confirm("Build the environment now (runs 'hud build')?", default=True)
+            if not ok:
+                raise typer.Exit(1)
+            require_docker_running()
+            build_environment(str(env_dir), platform="linux/amd64")
+        else:
+            hud_console.dim_info(
+                "Info",
+                "No hud.lock.yaml found nearby; skipping environment change checks.",
+            )
+            return {}
+
+    # Load lock file
+    try:
+        with open(lock_path) as f:
+            lock_data: dict[str, Any] = yaml.safe_load(f) or {}
+    except Exception:
+        lock_data = {}
+
+    # Fast change detection: recompute source hash and compare
+    try:
+        current_hash = compute_source_hash(env_dir)
+        stored_hash = (
+            (lock_data.get("build") or {}).get("sourceHash")
+            if isinstance(lock_data, dict)
+            else None
+        )
+        if stored_hash and current_hash and stored_hash != current_hash:
+            hud_console.warning("Environment sources changed since last build.")
+
+            # Show a brief diff summary to help users understand changes
+            diffs = _collect_source_diffs(env_dir, lock_data)
+
+            def _print_section(name: str, items: list[str]) -> None:
+                if not items:
+                    return
+                # Limit output to avoid flooding the console
+                preview = items[:20]
+                more = len(items) - len(preview)
+                hud_console.section_title(name)
+                for rel in preview:
+                    hud_console.dim_info("", rel)
+                if more > 0:
+                    hud_console.dim_info("", f"... and {more} more")
+
+            _print_section("Modified files", diffs.get("modified", []))
+            _print_section("Added files", diffs.get("added", []))
+            _print_section("Removed files", diffs.get("removed", []))
+
+            if interactive:
+                if hud_console.confirm("Rebuild now (runs 'hud build')?", default=True):
+                    require_docker_running()
+                    build_environment(str(env_dir), platform="linux/amd64")
+                    with open(lock_path) as f:
+                        lock_data = yaml.safe_load(f) or {}
+                else:
+                    hud_console.hint("Continuing without rebuild; this may use an outdated image.")
+            else:
+                hud_console.hint("Run 'hud build' to update the image before proceeding.")
+        elif not stored_hash:
+            hud_console.dim_info(
+                "Info",
+                "No source hash in lock; rebuild to enable change checks.",
+            )
+    except Exception as e:
+        hud_console.debug(f"Source hash check skipped: {e}")
+
+    return lock_data

hud/cli/utils/source_hash.py

@@ -0,0 +1,108 @@
+"""Utilities to compute a fast, deterministic source hash for environments.
+
+This intentionally focuses on the typical HUD environment layout and aims to be fast:
+- Always include: Dockerfile, pyproject.toml
+- Include directories: controller/, environment/, src/
+- Exclude common build/runtime caches and lock files
+
+Note: This is not a full Docker build context hash and does not parse .dockerignore.
+It is sufficient to detect meaningful changes for HUD environments quickly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+EXCLUDE_DIRS = {
+    ".git",
+    ".venv",
+    "dist",
+    "build",
+    "node_modules",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+
+EXCLUDE_FILE_SUFFIXES = {
+    ".pyc",
+    ".log",
+}
+
+EXCLUDE_FILES = {
+    "hud.lock.yaml",
+}
+
+INCLUDE_FILES = {"Dockerfile", "pyproject.toml"}
+INCLUDE_DIRS = {"controller", "environment"}
+
+
+def iter_source_files(root: Path) -> Iterable[Path]:
+    """Yield files to include in the source hash.
+
+    The order is not guaranteed; callers should sort for deterministic hashing.
+    """
+    # Always include top-level files if present
+    for name in INCLUDE_FILES:
+        p = root / name
+        if p.is_file():
+            yield p
+
+    # Include known directories
+    for d in INCLUDE_DIRS:
+        dp = root / d
+        if not dp.exists():
+            continue
+        for dirpath, dirnames, filenames in os.walk(dp):
+            # prune excluded dirs in-place
+            dirnames[:] = [dn for dn in dirnames if dn not in EXCLUDE_DIRS]
+            for fn in filenames:
+                if fn in EXCLUDE_FILES:
+                    continue
+                if any(fn.endswith(suf) for suf in EXCLUDE_FILE_SUFFIXES):
+                    continue
+                yield Path(dirpath) / fn
+
+
+def list_source_files(root: Path) -> list[Path]:
+    """Return a sorted list of files used for the source hash.
+
+    Sorting is by relative path to ensure deterministic ordering.
+    """
+    root = root.resolve()
+    files = list(iter_source_files(root))
+    files.sort(key=lambda p: str(p.resolve().relative_to(root)).replace("\\", "/"))
+    return files
+
+
+def compute_source_hash(directory: str | Path) -> str:
+    """Compute a deterministic SHA-256 hash over relevant source files.
+
+    Args:
+        directory: Environment directory root.
+
+    Returns:
+        Hex digest string.
+    """
+    root = Path(directory).resolve()
+    files = list_source_files(root)
+
+    hasher = hashlib.sha256()
+    for p in files:
+        rel = str(p.resolve().relative_to(root)).replace("\\", "/")
+        hasher.update(rel.encode("utf-8"))
+        with open(p, "rb") as f:
+            while True:
+                chunk = f.read(8192)
+                if not chunk:
+                    break
+                hasher.update(chunk)
+
+    return hasher.hexdigest()

hud/clients/base.py

@@ -139,7 +139,7 @@ class BaseHUDClient(AgentMCPClient):
                     raise HudAuthenticationError(
                         f'Sending authorization "{headers.get("Authorization", "")}", which may'
                         " be incomplete. Ensure HUD_API_KEY environment variable is set or send it"
-                        " as a header. You can get an API key at https://app.hud.so"
+                        " as a header. You can get an API key at https://hud.so"
                     )
             # Subclasses implement connection
             await self._connect(self._mcp_config)

hud/clients/fastmcp.py

@@ -95,7 +95,7 @@ class FastMCPHUDClient(BaseHUDClient):
                             raise RuntimeError(
                                 "Authentication failed for HUD API. "
                                 "Please ensure your HUD_API_KEY environment variable is set correctly."  # noqa: E501
-                                "You can get an API key at https://app.hud.so"
+                                "You can get an API key at https://hud.so"
                             ) from e
                     # Generic 401 error
                     raise RuntimeError(

hud/otel/config.py

@@ -111,7 +111,7 @@ def configure_telemetry(
         # Error if no exporters are configured
         raise ValueError(
             "No telemetry backend configured. Either:\n"
-            "1. Set HUD_API_KEY environment variable for HUD telemetry (https://app.hud.so)\n"
+            "1. Set HUD_API_KEY environment variable for HUD telemetry (https://hud.so)\n"
             "2. Use enable_otlp=True with configure_telemetry() for alternative backends (e.g., Jaeger)\n"  # noqa: E501
         )
     elif not settings.telemetry_enabled:

hud/otel/context.py

@@ -376,7 +376,7 @@ def _print_trace_url(task_run_id: str) -> None:
     if not (settings.telemetry_enabled and settings.api_key):
         return
 
-    url = f"https://app.hud.so/trace/{task_run_id}"
+    url = f"https://hud.so/trace/{task_run_id}"
     header = "🚀 See your agent live at:"
 
     # ANSI color codes
@@ -415,7 +415,7 @@ def _print_trace_complete_url(task_run_id: str, error_occurred: bool = False) ->
     if not (settings.telemetry_enabled and settings.api_key):
         return
 
-    url = f"https://app.hud.so/trace/{task_run_id}"
+    url = f"https://hud.so/trace/{task_run_id}"
 
     # ANSI color codes
     GREEN = "\033[92m"

hud/rl/vllm_adapter.py

@@ -36,7 +36,7 @@ class VLLMAdapter:
         headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
         payload = {"lora_name": adapter_name, "lora_path": adapter_path}
         # Implement exponential backoff for retrying the adapter load request.
-        max_retries = 5
+        max_retries = 8
         backoff_factor = 2
         delay = 1  # initial delay in seconds
 

hud/server/server.py

@@ -20,7 +20,6 @@ from hud.server.low_level import LowLevelServerWithInit
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Callable
 
-    from mcp.shared.context import RequestContext
     from starlette.requests import Request
 
 __all__ = ["MCPServer"]
@@ -37,6 +36,31 @@ def _run_with_sigterm(coro_fn: Callable[..., Any], *args: Any, **kwargs: Any) ->
 
     sys.stderr.flush()
 
+    # Check if we're already in an event loop
+    try:
+        loop = asyncio.get_running_loop()
+        logger.warning(
+            "HUD server is running in an existing event loop. "
+            "SIGTERM handling may be limited. "
+            "Consider using await hub.run_async() instead of hub.run() in async contexts."
+        )
+
+        task = loop.create_task(coro_fn(*args, **kwargs))
+
+        # Try to handle SIGTERM if possible
+        if sys.platform != "win32":
+
+            def handle_sigterm(signum: Any, frame: Any) -> None:
+                logger.info("SIGTERM received in async context, cancelling task...")
+                loop.call_soon_threadsafe(task.cancel)
+
+            signal.signal(signal.SIGTERM, handle_sigterm)
+
+        return
+
+    except RuntimeError:
+        pass
+
     async def _runner() -> None:
         stop_evt: asyncio.Event | None = None
         if sys.platform != "win32" and os.getenv("FASTMCP_DISABLE_SIGTERM_HANDLER") != "1":
@@ -127,7 +151,11 @@ class MCPServer(FastMCP):
                     # Force flush logs to ensure they're visible
                     sys.stderr.flush()
 
-                    if self._shutdown_fn is not None and _sigterm_received:
+                    if (
+                        self._shutdown_fn is not None
+                        and _sigterm_received
+                        and not self._shutdown_has_run
+                    ):
                         logger.info("SIGTERM detected! Calling @mcp.shutdown handler...")
                         sys.stderr.flush()
                         try:
@@ -137,7 +165,9 @@ class MCPServer(FastMCP):
                         except Exception as e:
                             logger.error("Error during @mcp.shutdown: %s", e)
                             sys.stderr.flush()
-                        _sigterm_received = False
+                        finally:
+                            self._shutdown_has_run = True
+                            _sigterm_received = False
                     elif self._shutdown_fn is not None:
                         logger.info(
                             "No SIGTERM. This is a hot reload (SIGINT) or normal exit. Skipping @mcp.shutdown handler."  # noqa: E501
@@ -153,27 +183,53 @@ class MCPServer(FastMCP):
         self._initializer_fn: Callable | None = None
         self._did_init = False
         self._replaced_server = False
+        self._shutdown_has_run = False  # Guard against double-execution of shutdown hook
 
     def _replace_with_init_server(self) -> None:
         """Replace the low-level server with init version when needed."""
         if self._replaced_server:
             return
 
-        def _run_init(ctx: RequestContext | None = None) -> Any:
+        async def _run_init(ctx: object | None = None) -> None:
+            """Run the user initializer exactly once, with stdout redirected."""
             if self._initializer_fn is not None and not self._did_init:
                 self._did_init = True
-                # Redirect stdout to stderr during initialization to prevent
-                # any library prints from corrupting the MCP protocol
+                # Prevent stdout from polluting the MCP protocol on stdio/HTTP
                 with contextlib.redirect_stdout(sys.stderr):
-                    # Check if function accepts ctx parameter
                     import inspect
 
-                    sig = inspect.signature(self._initializer_fn)
-                    if "ctx" in sig.parameters:
-                        return self._initializer_fn(ctx)
+                    fn = self._initializer_fn
+                    sig = inspect.signature(fn)
+                    params = sig.parameters
+
+                    ctx_param = params.get("ctx") or params.get("_ctx")
+                    if ctx_param is not None:
+                        if ctx_param.kind == inspect.Parameter.KEYWORD_ONLY:
+                            result = fn(**{ctx_param.name: ctx})
+                        else:
+                            result = fn(ctx)
                     else:
-                        # Call without ctx for simpler usage
-                        return self._initializer_fn()
+                        required_params = [
+                            p
+                            for p in params.values()
+                            if p.default is inspect._empty
+                            and p.kind
+                            in (
+                                inspect.Parameter.POSITIONAL_ONLY,
+                                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                                inspect.Parameter.KEYWORD_ONLY,
+                            )
+                        ]
+                        if required_params:
+                            param_list = ", ".join(p.name for p in required_params)
+                            raise TypeError(
+                                "Initializer must accept no args or a single `ctx` argument; "
+                                f"received required parameters: {param_list}"
+                            )
+                        result = fn()
+                    if inspect.isawaitable(result):
+                        await result
+                    return None
             return None
 
         # Save the old server's handlers before replacing it
@@ -258,7 +314,22 @@ class MCPServer(FastMCP):
             self._register_hud_helpers()
             logger.info("Registered HUD helper endpoints at /hud/*")
 
-        await super().run_async(transport=transport, show_banner=show_banner, **transport_kwargs)
+        try:
+            await super().run_async(
+                transport=transport, show_banner=show_banner, **transport_kwargs
+            )
+        finally:
+            # Fallback: ensure SIGTERM-triggered shutdown runs even when a custom
+            # lifespan bypasses our default fastmcp shutdown path.
+            global _sigterm_received
+            if self._shutdown_fn is not None and _sigterm_received and not self._shutdown_has_run:
+                try:
+                    await self._shutdown_fn()
+                except Exception as e:  # pragma: no cover - defensive logging
+                    logger.error("Error during @mcp.shutdown (fallback): %s", e)
+                finally:
+                    self._shutdown_has_run = True
+                    _sigterm_received = False
 
     # Tool registration helper -- appends BaseTool to FastMCP
     def add_tool(self, obj: Any, **kwargs: Any) -> None:

hud/server/tests/test_add_tool.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any, cast
+
+from hud.server import MCPServer
+
+
+def test_add_tool_accepts_base_tool(monkeypatch):
+    """If obj is BaseTool, its `.mcp` gets passed through to FastMCP.add_tool."""
+    # Stub hud.tools.base.BaseTool and capture FastMCP.add_tool calls
+    mod = types.ModuleType("hud.tools.base")
+
+    class FakeBaseTool:
+        """Stub type checked by isinstance() inside add_tool."""
+
+    # Tell the type checker we're mutating a dynamic module
+    mod_any = cast("Any", mod)
+    mod_any.BaseTool = FakeBaseTool
+    monkeypatch.setitem(sys.modules, "hud.tools.base", mod)
+
+    calls: dict[str, object | None] = {"obj": None, "kwargs": None}
+
+    def fake_super_add(self, obj: object, **kwargs: object) -> None:  # keep runtime the same
+        calls["obj"] = obj
+        calls["kwargs"] = kwargs
+
+    monkeypatch.setattr("hud.server.server.FastMCP.add_tool", fake_super_add, raising=True)
+
+    mcp = MCPServer(name="AddTool")
+    sentinel = object()
+
+    class MyTool(FakeBaseTool):
+        def __init__(self) -> None:
+            self.mcp = sentinel
+
+    mcp.add_tool(MyTool(), extra="yes")
+    assert calls["obj"] is sentinel
+    assert isinstance(calls["kwargs"], dict)
+    assert calls["kwargs"]["extra"] == "yes"
+
+
+def test_add_tool_plain_falls_back_to_super(monkeypatch):
+    """Non-BaseTool objects are passed unchanged to FastMCP.add_tool."""
+    calls = []
+
+    def fake_super_add(self, obj, **kwargs):
+        calls.append((obj, kwargs))
+
+    monkeypatch.setattr("hud.server.server.FastMCP.add_tool", fake_super_add, raising=True)
+
+    mcp = MCPServer(name="AddToolPlain")
+
+    async def fn():  # pragma: no cover - never awaited by FastMCP here
+        return "ok"
+
+    mcp.add_tool(fn, desc="x")
+    assert calls and calls[0][0] is fn
+    assert calls[0][1]["desc"] == "x"