Python: Fix hyperlight WasmSandbox cross-thread Drop and harden hosted-agent sample (#5603)

* update hyperlight to beta and move samples, add hosted agent sample

* Python: Fix hyperlight WasmSandbox cross-thread Drop and harden sample

Root cause: when a worker-side closure raised, the exception's __traceback__
retained frame locals that included the partially constructed PyO3 sandbox.
Future.result() re-raised that exception on the caller thread, and when the
caller's exception was eventually GC'd the frame locals were released
off-thread, dec_ref'ing the unsendable sandbox from the wrong thread and
tripping the PyO3 panic
'_native_wasm::WasmSandbox is unsendable, but is being dropped on another thread'.

Fix:
* Add _SandboxWorker._run_on_worker which catches every exception on the
  worker, drops __traceback__ there, deletes the original exception, and
  re-raises a fresh instance on the caller thread. initialize and execute
  route through it; dispose keeps its bare-submit semantics.
* Add an opt-in diagnostic module _drop_diagnostic (no-op unless
  HYPERLIGHT_TRACE_DROPS=1) that installs a sys.unraisablehook and dumps
  owner-thread + per-thread stacks on any future cross-thread unsendable
  Drop. Useful for triaging similar PyO3 regressions.
* Tests: cross-thread invocation, traceback-leak isolation, _SandboxEntry
  attribute-shape check, and a stale-reference stress test driven through
  asyncio.to_thread.

Sample (samples/04-hosting/foundry-hosted-agents/responses/06_hyperlight_codeact):
* Dockerfile installs agent-framework-* from in-tree source with python/ as
  build context so unreleased fixes can be validated end-to-end.
* call_server.py pins the Responses API version.
* main.py enables include_detailed_errors=True so future tool failures
  surface the actual exception text instead of a bare 'Error: Function
  failed.' string.
* README.md documents the in-tree-package build and the Hyperlight
  hypervisor requirement (/dev/kvm on Linux, MSHV on Windows). Hosted
  environments without hypervisor passthrough surface 'No Hypervisor was
  found for Sandbox'; this is a hosting constraint, not a hyperlight bug.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: remove _drop_diagnostic from hyperlight package

The diagnostic module was useful while bisecting the cross-thread Drop bug,
but it is no longer needed now that _SandboxWorker._run_on_worker prevents
the panic at the source.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: address PR review feedback on hyperlight

- Use lazy agent_framework.hyperlight import in sample main.py.
- Env-driven endpoint (FOUNDRY_AGENT_ENDPOINT) in call_server.py; remove personal URLs.
- Align agent.yaml model deployment with manifest (gpt-4.1-mini).
- Tighten Dockerfile requirements guard; drop dangling deploy.ps1 reference.
- Preserve exception args when sanitizing tracebacks in _run_on_worker.
- Add public _SandboxWorker.is_alive(); update test to avoid private attr.
- Add namespace coverage tests for agent_framework.hyperlight lazy loader.
- Add prominent note: Foundry hosted-agent runtime does not yet support
  Hyperlight (no hypervisor exposed); container works locally with /dev/kvm.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: bump hyperlight-sandbox dependencies to 0.4.x

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: renumber hyperlight codeact sample to 08

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Coerce worker exception args to strings for cross-thread safety

Stringify exc.args on the worker thread before propagating, so any
PyO3 unsendable object captured in args (e.g. via a caller-supplied
callback or underlying SDK) cannot be Dropped on the calling thread.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* moved sample

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/core/agent_framework/hyperlight/__init__.py

@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Hyperlight CodeAct namespace for optional Agent Framework connectors.
+
+This module lazily re-exports objects from ``agent-framework-hyperlight``.
+"""
+
+import importlib
+from typing import Any
+
+_IMPORTS: dict[str, tuple[str, str]] = {
+    "AllowedDomain": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+    "AllowedDomainInput": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+    "FileMount": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+    "FileMountInput": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+    "HyperlightCodeActProvider": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+    "HyperlightExecuteCodeTool": ("agent_framework_hyperlight", "agent-framework-hyperlight"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _IMPORTS:
+        import_path, package_name = _IMPORTS[name]
+        try:
+            return getattr(importlib.import_module(import_path), name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                f"The package {package_name} is required to use `{name}`. "
+                f"Please use `pip install {package_name}`, or update your requirements.txt or pyproject.toml file."
+            ) from exc
+    raise AttributeError(f"Module `hyperlight` has no attribute {name}.")
+
+
+def __dir__() -> list[str]:
+    return list(_IMPORTS.keys())

python/packages/core/pyproject.toml

@@ -48,6 +48,7 @@ all = [
     "agent-framework-foundry",
     "agent-framework-foundry-local",
     "agent-framework-github-copilot; python_version >= '3.11'",
+    "agent-framework-hyperlight; ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')) and python_version < '3.14'",
     "agent-framework-lab",
     "agent-framework-mem0",
     "agent-framework-ollama",

python/packages/core/tests/core/test_hyperlight_namespace.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from types import ModuleType
+
+import pytest
+
+import agent_framework.hyperlight as hyperlight
+
+
+def test_hyperlight_namespace_dir_lists_lazy_exports() -> None:
+    names = dir(hyperlight)
+    for expected in (
+        "AllowedDomain",
+        "AllowedDomainInput",
+        "FileMount",
+        "FileMountInput",
+        "HyperlightCodeActProvider",
+        "HyperlightExecuteCodeTool",
+    ):
+        assert expected in names
+
+
+def test_hyperlight_namespace_lazy_loads_known_attribute(monkeypatch: pytest.MonkeyPatch) -> None:
+    sentinel = object()
+    fake_module = ModuleType("agent_framework_hyperlight")
+    fake_module.HyperlightCodeActProvider = sentinel  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "agent_framework_hyperlight", fake_module)
+
+    assert hyperlight.HyperlightCodeActProvider is sentinel
+
+
+def test_hyperlight_namespace_unknown_attribute_raises_attribute_error() -> None:
+    with pytest.raises(AttributeError, match="Module `hyperlight` has no attribute DoesNotExist."):
+        _ = hyperlight.DoesNotExist  # type: ignore[attr-defined]
+
+
+def test_hyperlight_namespace_missing_package_raises_helpful_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setitem(sys.modules, "agent_framework_hyperlight", None)
+
+    with pytest.raises(ModuleNotFoundError, match="agent-framework-hyperlight"):
+        _ = hyperlight.HyperlightCodeActProvider