Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions python/packages/hyperlight/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,39 @@ Initialization, snapshot restore, and execution failures follow the same policy.
Failed sandbox entries are retired; cancellation and system-exit signals still
propagate without becoming ordinary execution errors.

## Execution limits

Guest execution has a finite 30-second budget by default. Both
`HyperlightCodeActProvider` and `HyperlightExecuteCodeTool` accept the host-side
`execution_timeout_seconds` option, which must be a positive finite number.
Applications that intentionally run longer must configure a larger budget.
The option is captured in provider run snapshots and serialized state; it is
not a model-controlled `execute_code` argument.

Reaching the budget returns an error content with
`Code execution exceeded its time limit.` Caller task cancellation interrupts
guest execution and propagates `asyncio.CancelledError`. Cancellation waits for
native execution and its interruption thread to finish, even if the caller
cancels again. Queued cancellation does not interrupt another invocation.
The next invocation restores the warm snapshot before reusing the sandbox.

The budget starts on the sandbox's owning worker, not while waiting for that
worker. Initialization and warm-up share the invocation's budget, but runtime
initialization and host tool callbacks cannot be interrupted. Host tools must
enforce their own cancellation and time limits. Completed results and unrelated
execution failures are not replaced with a timeout that arrives late.

This behavior uses the cross-thread `Sandbox.interrupt_handle()` API included
in the required Hyperlight SDK 0.9.0 or later.

To run the native regressions on a KVM host with the required SDK and both
backends installed:

```bash
HYPERLIGHT_RUN_GUEST_TESTS=true uv run --directory python/packages/hyperlight pytest \
tests/hyperlight/test_execution_limits.py -m integration
```

## Installation

```bash
Expand Down

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
from agent_framework._tools import ApprovalMode, _ToolDescriptionFormat # pyright: ignore[reportPrivateUsage]

from ._execute_code_tool import (
DEFAULT_EXECUTION_TIMEOUT_SECONDS,
DEFAULT_MAX_OUTPUT_FILE_BYTES,
DEFAULT_MAX_OUTPUT_FILES,
DEFAULT_MAX_OUTPUT_TOTAL_BYTES,
Expand All @@ -31,6 +32,8 @@ class HyperlightCodeActProvider(ContextProvider):
Mappings are copied, including entries for tools registered later.
include_detailed_errors: Expose host exception and execution diagnostics only for a trusted
channel. Defaults to ``False`` and is independent of outer-client error/logging settings.
execution_timeout_seconds: Positive finite guest execution budget, in seconds. Defaults to 30.
Runtime initialization and host tool callbacks cannot be interrupted.
"""

DEFAULT_SOURCE_ID = "hyperlight_codeact"
Expand All @@ -49,6 +52,7 @@ def __init__(
max_output_files: int = DEFAULT_MAX_OUTPUT_FILES,
max_output_file_bytes: int = DEFAULT_MAX_OUTPUT_FILE_BYTES,
max_output_total_bytes: int = DEFAULT_MAX_OUTPUT_TOTAL_BYTES,
execution_timeout_seconds: float = DEFAULT_EXECUTION_TIMEOUT_SECONDS,
backend: str = "wasm",
module: str | None = "python_guest.path",
module_path: str | None = None,
Expand All @@ -66,6 +70,7 @@ def __init__(
max_output_files=max_output_files,
max_output_file_bytes=max_output_file_bytes,
max_output_total_bytes=max_output_total_bytes,
execution_timeout_seconds=execution_timeout_seconds,
backend=backend,
module=module,
module_path=module_path,
Expand Down
6 changes: 3 additions & 3 deletions python/packages/hyperlight/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ classifiers = [
]
dependencies = [
"agent-framework-core>=1.19.0,<2",
"hyperlight-sandbox>=0.8.0,<0.9",
"hyperlight-sandbox-backend-wasm>=0.8.0,<0.9 ; (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')",
"hyperlight-sandbox-python-guest>=0.8.0,<0.9",
"hyperlight-sandbox>=0.9.0,<0.10",
"hyperlight-sandbox-backend-wasm>=0.9.0,<0.10 ; (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')",
"hyperlight-sandbox-python-guest>=0.9.0,<0.10",
]

[tool.uv]
Expand Down
Loading
Loading