fix(hyperlight-codeact): pin version >=0.3.0 and handle Python 3.14+

skills/hyperlight-codeact/SKILL.md

@@ -53,7 +53,10 @@ Sandboxed code can only reach the outside world through `call_tool()` bridges.
 python3 scripts/codeact.py --discover
 
 # 2. Run code (uv auto-installs hyperlight-sandbox into an ephemeral env)
-uv run --with 'hyperlight-sandbox[wasm,python_guest]' python3 scripts/codeact.py --auto --workspace . --code '
+#    NOTE: The Wasm backend requires Python ≤3.13. Use --python 3.13 if your
+#    system default is newer. Pin >=0.3.0 to avoid the empty stub package.
+uv run --python 3.13 --with 'hyperlight-sandbox[wasm,python_guest]>=0.3.0' \
+  python3 scripts/codeact.py --auto --workspace . --code '
 content = call_tool("view", path="README.md")
 print(f"README has {len(content.splitlines())} lines")
 '
@@ -100,14 +103,20 @@ content = call_tool('view', path=call_tool('glob', pattern='config.json')[0])
 
 ### Step 3 -- Execute
 
-Use `uv run --with` to auto-install the dependency:
+Use `uv run --with` to auto-install the dependency.
+
+**Important:** The Wasm backend only has wheels for Python ≤3.13. If your
+system Python is 3.14+, add `--python 3.13` to the `uv run` command. Always
+pin `>=0.3.0` — earlier versions are stub packages without the `Sandbox` class.
 
 ```bash
 # Auto-discover + workspace scoping (recommended)
-uv run --with 'hyperlight-sandbox[wasm,python_guest]' python3 scripts/codeact.py --auto --workspace . --code '...'
+uv run --python 3.13 --with 'hyperlight-sandbox[wasm,python_guest]>=0.3.0' \
+  python3 scripts/codeact.py --auto --workspace . --code '...'
 
 # With saved manifest
-uv run --with 'hyperlight-sandbox[wasm,python_guest]' python3 scripts/codeact.py --manifest tools.json --code-file script.py
+uv run --python 3.13 --with 'hyperlight-sandbox[wasm,python_guest]>=0.3.0' \
+  python3 scripts/codeact.py --manifest tools.json --code-file script.py
 ```
 
 If `hyperlight-sandbox` is already installed, plain `python3` works too:
@@ -134,6 +143,9 @@ Main executor. Key flags:
 
 ## Prerequisites
 
-- Python 3.10+
+- Python 3.10–3.13 (the Wasm backend does **not** have wheels for 3.14+)
 - `uv` (recommended — auto-installs `hyperlight-sandbox` with no side effects)
-- Or: `pip install 'hyperlight-sandbox[wasm,python_guest]'`
+- Or: `pip install 'hyperlight-sandbox[wasm,python_guest]>=0.3.0'`
+
+> **Tip:** If your system Python is 3.14+, use `uv run --python 3.13 ...` to
+> automatically fetch and use a compatible interpreter.

skills/hyperlight-codeact/scripts/codeact.py

@@ -509,6 +509,68 @@ def _try_install(package: str, import_name: str):
     return None
 
 
+# Minimum version that exports the Sandbox class and Wasm backend.
+_MIN_VERSION = "0.3.0"
+# Maximum Python version with pre-built Wasm backend wheels.
+_MAX_PYTHON = (3, 13)
+
+
+def _check_python_version() -> None:
+    """Warn if the current Python is too new for pre-built Wasm wheels."""
+    if sys.version_info[:2] > _MAX_PYTHON:
+        max_str = f"{_MAX_PYTHON[0]}.{_MAX_PYTHON[1]}"
+        cur_str = f"{sys.version_info.major}.{sys.version_info.minor}"
+        print(
+            f"\n⚠  Python {cur_str} detected. The hyperlight-sandbox Wasm backend "
+            f"only ships wheels for Python ≤{max_str}.\n"
+            f"   Re-run with:  uv run --python {max_str} "
+            f"--with 'hyperlight-sandbox[wasm,python_guest]>={_MIN_VERSION}' "
+            f"python3 scripts/codeact.py ...\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _import_sandbox():
+    """Import the Sandbox class, giving actionable errors on failure."""
+    # 1. Check Python version first — avoids confusing resolution errors.
+    _check_python_version()
+
+    # 2. Try the import.
+    try:
+        from hyperlight_sandbox import Sandbox
+        return Sandbox
+    except ImportError:
+        pass
+
+    # 3. Check if hyperlight_sandbox is installed but too old (stub package).
+    try:
+        import hyperlight_sandbox as _hl
+        ver = getattr(_hl, "__version__", "0.0.0")
+        if not hasattr(_hl, "Sandbox"):
+            print(
+                f"\n✗ hyperlight-sandbox {ver} is installed but does not "
+                f"export Sandbox (likely a stub package).\n"
+                f"  Install version ≥{_MIN_VERSION}:\n"
+                f"    uv run --python {_MAX_PYTHON[0]}.{_MAX_PYTHON[1]} "
+                f"--with 'hyperlight-sandbox[wasm,python_guest]>={_MIN_VERSION}' "
+                f"python3 scripts/codeact.py ...\n",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+    except ImportError:
+        pass
+
+    # 4. Not installed at all — try interactive install.
+    _mod = _try_install(
+        f"hyperlight-sandbox[wasm,python_guest]>={_MIN_VERSION}",
+        "hyperlight_sandbox",
+    )
+    if _mod is None:
+        sys.exit(1)
+    return _mod.Sandbox
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -559,13 +621,7 @@ def main() -> None:
         return
 
     # ---- execution ----
-    try:
-        from hyperlight_sandbox import Sandbox
-    except ImportError:
-        _mod = _try_install("hyperlight-sandbox[wasm,python_guest]", "hyperlight_sandbox")
-        if _mod is None:
-            sys.exit(1)
-        Sandbox = _mod.Sandbox
+    Sandbox = _import_sandbox()
 
     global _WORKSPACE_ROOT
     if args.workspace: