[Vincent Biret (baywet)]

Motivation & Context

Cancelling an asynchronous Hyperlight invocation should stop its guest execution before the sandbox can be reused. Python guest execution also needs a finite default budget, consistent with the .NET work in #10066.

Description & Review Guide

• What are the major changes? Add a positive finite execution_timeout_seconds option to the tool and provider, defaulting to 30 seconds. Forward cancellation through an independently owned SDK interruption handle, wait for the native worker and interruption monitor to finish, and restore the warm snapshot before reuse. Capture the setting in provider run snapshots and serialized state. Add focused unit and real-guest regressions and update consumer guidance.
• What is the impact of these changes? Guest execution is no longer unlimited by default; applications that intentionally run longer must configure a larger budget. Timeout returns error content, while caller cancellation remains asyncio.CancelledError. Runtime initialization and host tool callbacks cannot be interrupted and must enforce their own limits.
• What do you want reviewers to focus on? Native owner-thread confinement, cancellation during host callbacks and queued work, repeated cancellation, budget capture, and recovery after interruption.

Dependency prerequisite: This draft requires the Python Sandbox.interrupt_handle() API from hyperlight-dev/hyperlight-sandbox#275. The declared released dependency does not yet provide it. A compatible SDK release and dependency-floor update are required before shipping; no local source paths are committed.

Validation used temporary Linux x64 Azure KVM containers linked to SDK revision 530672881443ac26973688191a18f180dc373efd. The three original real-guest regressions failed for the intended behavior before implementation changes.

Commands below ran from python/packages/hyperlight with that source-linked environment:

• python -m pytest tests/hyperlight/test_execution_limits.py tests/hyperlight/test_execution_control.py -v --tb=short with HYPERLIGHT_RUN_GUEST_TESTS=true: 8 passed, covering Python/Wasm and native JavaScript.
• python -m pytest tests -k "not pings_bing" --tb=short with HYPERLIGHT_RUN_GUEST_TESTS=true: 267 passed, 6 platform skips, 1 deselected, with the pre-existing warning described below.
• python -m pytest tests -k pings_bing --tb=short with networking enabled: 1 passed.
• python -m pytest -m 'not integration' --cov=agent_framework_hyperlight --cov-report=term-missing:skip-covered --cov-fail-under=85 tests --tb=short: 247 passed, 6 platform skips, 21 deselected; 88.31% coverage, above the 85% gate.
• ruff check --no-fix . and ruff format --check .: passed with the repository-pinned Ruff.
• pyright --pythonpath /src/.venv/bin/python: passed, 0 errors for source.

The configured test-typing profiles ran from python:

• mypy --config-file pyproject.toml --explicit-package-bases --namespace-packages --python-executable /src/.venv/bin/python packages/hyperlight/tests: passed.
• pyrefly check -c pyrefly.toml packages/hyperlight/tests: passed.
• ty check packages/hyperlight/tests: passed.
• zuban mypy --config-file pyproject.toml packages/hyperlight/tests: passed.
• pyright -p pyrightconfig.tests.json --pythonpath /src/.venv/bin/python packages/hyperlight/tests: passed.

The full package run reports a native WasmSandbox cross-thread finalization warning. Repeating the existing host-error and owner-thread tests with unchanged production code from main and the same SDK reproduces it: python -m pytest tests/hyperlight/test_hyperlight_codeact.py -k 'host_error_policy_with_real_sandbox or sandbox_run_result_is_finalized_on_owner_thread' --tb=short -W error::pytest.PytestUnraisableExceptionWarning produced 4 passed, 1 failed because the warning was promoted to an error. This draft does not claim that existing warning is fixed.

Cross-language checks used the same updated SDK and the unchanged #10066 source. /src was the SDK checkout and /linked-sdk.targets replaced the .NET package reference with its local project:

• From the SDK root, python -m unittest discover -s src/sdk/python/core/tests -p test_interruption.py -v: 4 passed, each exercising both backends.
• dotnet vstest /src/src/sdk/dotnet/core/Tests/HyperlightSandbox.Tests/bin/Debug/net8.0/HyperlightSandbox.Tests.dll --Logger:"console;verbosity=normal": 152 passed.
• From the Agent Framework dotnet directory, dotnet test --project tests/Microsoft.Agents.AI.Hyperlight.UnitTests -f net10.0 --no-build --no-restore -p:CustomAfterMicrosoftCommonTargets=/linked-sdk.targets -p:HyperlightGuestTests=true: 62 passed, 0 skipped.
• From that same directory, dotnet test --project tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests -f net10.0 --no-build --no-restore -p:CustomAfterMicrosoftCommonTargets=/linked-sdk.targets -p:JsonSerializerIsReflectionEnabledByDefault=true: 5 passed, 0 skipped.

Temporary Azure resources were deleted and their absence verified.

Related Issue

Related to #10066, which implements the .NET counterpart. This PR implements the Python integration rather than duplicating that work.

Depends on hyperlight-dev/hyperlight-sandbox#275. No separate Agent Framework issue is linked.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: GitHub Copilot assisted with implementation, regression tests, documentation, validation, and this PR description.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.