Skip to content

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

Merged
jsturtevant merged 1 commit into
mainfrom
fix/hyperlight-python-compat
Apr 24, 2026
Merged

jsturtevant merged 1 commit into
mainfrom
fix/hyperlight-python-compat

Conversation

@jsturtevant

Copy link
Copy Markdown
Owner

Problem

When using the hyperlight-codeact skill, three issues prevent it from working first-try:

  1. Stub package resolutionuv run --with 'hyperlight-sandbox[wasm,python_guest]' resolves to v0.0.1, which is an empty stub with no Sandbox class. The import fails with ImportError: cannot import name 'Sandbox'.

  2. Python 3.14+ ABI mismatch — The hyperlight-sandbox-backend-wasm package only ships wheels for Python ≤3.13. On Python 3.14+ (now the default on many systems), uv fails to find a compatible wheel.

  3. Unhelpful fallback — The _try_install function tries interactive pip/uv installs, which don't help in uv run ephemeral environments and give no indication of what actually went wrong.

Fix

scripts/codeact.py

  • Add _check_python_version() — early-exits with a clear message and the exact uv run --python 3.13 command to use
  • Add _import_sandbox() — detects stub packages (installed but no Sandbox attr) with an actionable error, then falls back to interactive install with the pinned version
  • Pin >= in the install prompt so the stub package is never installed

SKILL.md

  • Pin >=0.3.0 in all uv run --with examples
  • Add --python 3.13 to all execution examples
  • Update prerequisites to document Python 3.10–3.13 requirement
  • Add tip about using uv run --python 3.13 on newer systems

…compatibility

Problems encountered when using the skill:

1. `uv run --with 'hyperlight-sandbox[wasm,python_guest]'` resolved to
   v0.0.1, a stub package with no Sandbox class. Fix: pin >=0.3.0.

2. The Wasm backend (hyperlight-sandbox-backend-wasm) only ships wheels
   for Python <=3.13. On Python 3.14+ uv fails with an ABI mismatch.
   Fix: add --python 3.13 to all uv run examples and add runtime
   detection with an actionable error message.

3. The _try_install fallback was unhelpful when running inside
   `uv run --with` (ephemeral env). Fix: add _import_sandbox() that
   detects stub versions and Python ABI mismatches before falling back
   to interactive install.

Changes:
- scripts/codeact.py: Add _check_python_version(), _import_sandbox()
  with version/ABI detection and clear error messages
- SKILL.md: Pin >=0.3.0, add --python 3.13, document Python <=3.13
  requirement in prerequisites
@jsturtevant
jsturtevant merged commit e9d49be into main Apr 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant