Python: Bound Hyperlight output attachments

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Untrusted code in a filesystem-enabled Hyperlight sandbox can create output files with attacker-controlled logical sizes. Reading those files without quotas can allocate proportional host memory and then allocate again while constructing inline base64 data URIs, allowing a sparse guest file to exhaust the trusted host process.

This change bounds Agent Framework's output attachment discovery and materialization, and surfaces quota or allocation failures as structured execution errors while preserving sandbox stdout. Guest-side filesystem creation and output-tree cleanup limits remain the responsibility of Hyperlight.

Description & Review Guide

• What are the major changes? Adds always-finite output quotas (20 files, 5 MiB per file, and 20 MiB cumulative raw bytes by default) to HyperlightExecuteCodeTool and HyperlightCodeActProvider; validates and forwards them through run-scoped tools and serializable state; uses only bounded streaming filesystem discovery rather than the backend's eager output listing; bounds every entry visited during attachment discovery, nesting depth, and simultaneously open scanner set; opens the output root and path components through pinned no-follow directory descriptors where supported; verifies identities and logical size on the opened descriptor; performs verified-size-plus-one reads capped by the remaining allowances; and delays Content.from_data until every output has passed validation and byte limits.
• What is the impact of these changes? During attachment collection, oversized, directory-heavy, enumeration-failing, or allocation-failing output returns a structured execution error with no partial data attachments. Trusted applications can raise each public attachment limit with positive integers, but cannot disable limits. Platforms without secure directory-relative opens fail closed for nested attachments while retaining reparse and identity checks for direct /output children. The PR does not attempt to bound guest file/tree creation or recursive cleanup of an already-created tree; those controls belong in Hyperlight.
• What do you want reviewers to focus on? Please focus on the finite attachment-discovery work/FD policy, filesystem-only discovery, the root-pinned component walk and fail-closed fallback, cumulative accounting, and the decision to keep quotas invocation-scoped rather than part of the shared sandbox cache identity.

Related Issue

Related to #8055. This focused hardening was prompted by a privately shared Hyperlight output-handling report; it intentionally leaves the framework-level artifact-store design for future work and guest filesystem creation limits to Hyperlight, and therefore does not close #8055. No competing PR for this Hyperlight fix was found.

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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.

[Copilot]

🟡 Changes recommended

Output enumeration remains unbounded, and intermediate path components remain vulnerable to TOCTOU replacement.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Hardens Hyperlight output attachments against host-memory exhaustion with finite invocation-scoped quotas.

Changes:

• Adds configurable file-count and byte limits.
• Uses descriptor validation and bounded reads before encoding.
• Adds documentation and unit/integration coverage.

File summaries

File	Description
python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py	Implements quota enforcement and bounded materialization.
python/packages/hyperlight/agent_framework_hyperlight/_provider.py	Forwards quota configuration.
python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py	Tests limits, failures, and propagation.
python/packages/hyperlight/README.md	Documents defaults and configuration.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 5263ed9450de
Model: gpt-5.6-sol-fast

Overview

The change adds finite invocation-scoped attachment quotas, validates their public configuration, performs descriptor-based bounded reads, and delays base64 materialization until all outputs pass validation. Tests cover sparse files, file growth, cumulative accounting, shared-registry behavior, and structured handling of read and encoding allocation failures. Two residual gaps remain: output discovery is still unbounded before the new file-count gate, and accepted extreme byte limits can raise an uncaught OverflowError.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (1 high, 1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py