Python: Add Hyperlight CodeAct package and docs

[eavanvalkenburg]

Motivation and Context

Add a concrete, optional CodeAct implementation for Python and capture the cross-SDK design for CodeAct with Hyperlight. This provides a reusable path for long-running agents to execute sandboxed code with provider-owned tools, file mounts, and network allow-lists without baking CodeAct into core.

Description

• add ADR 0024 plus Python feature design notes for the CodeAct and Hyperlight design
• introduce the alpha agent-framework-hyperlight package with HyperlightCodeActProvider and HyperlightExecuteCodeTool
• add provider-managed tool, file, and network CRUD; derived approval behavior; serializable provider state; and Hyperlight-backed execution results
• move the CodeAct samples into the new package and update workspace/package metadata
• add unit coverage, a guarded real-sandbox integration test, and wire Hyperlight into the Python misc integration workflow

Closes: #5187

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

Adds an optional Python Hyperlight-backed CodeAct implementation plus cross-SDK design documentation, and wires the new package into the Python workspace and CI.

Changes:

• Introduces the new agent-framework-hyperlight alpha package (provider + execute_code tool), including samples and tests.
• Updates agent-framework-core to let context providers inspect/override per-run runtime tools via SessionContext.options["tools"].
• Adds ADR/design docs for CodeAct and updates Python CI workflows to include Hyperlight integration coverage.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
python/uv.lock	Adds Hyperlight package + Hyperlight sandbox deps; updates a few dependency markers.
python/pyproject.toml	Registers agent-framework-hyperlight in the Python workspace.
python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py	Adds unit coverage + guarded real-sandbox integration test.
python/packages/hyperlight/samples/README.md	Documents how to run the new Hyperlight samples.
python/packages/hyperlight/samples/codeact_tool.py	Standalone HyperlightExecuteCodeTool sample.
python/packages/hyperlight/samples/codeact_context_provider.py	Provider-owned CodeAct sample using HyperlightCodeActProvider.
python/packages/hyperlight/README.md	Package-level README for installation and public API.
python/packages/hyperlight/pyproject.toml	New package metadata, deps, and tooling config.
python/packages/hyperlight/LICENSE	Adds MIT license for the new package.
python/packages/hyperlight/agent_framework_hyperlight/_types.py	Adds public types (FileMount, FilesystemMode, NetworkMode).
python/packages/hyperlight/agent_framework_hyperlight/_provider.py	Implements HyperlightCodeActProvider context provider.
python/packages/hyperlight/agent_framework_hyperlight/_instructions.py	Builds dynamic CodeAct instructions and tool descriptions.
python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py	Implements sandbox execution, caching, CRUD registries for tools/files/network.
python/packages/hyperlight/agent_framework_hyperlight/init.py	Exposes public API + version metadata.
python/packages/core/tests/core/test_agents.py	Adds tests validating providers can inspect/remove runtime tools.
python/packages/core/agent_framework/_tools.py	Introduces ApprovalMode type alias and updates signatures.
python/packages/core/agent_framework/_sessions.py	Updates docs to reflect provider mutability of options["tools"].
python/packages/core/agent_framework/_agents.py	Passes runtime tools via SessionContext.options and resolves tools from provider-mutated options.
python/PACKAGE_STATUS.md	Adds agent-framework-hyperlight as alpha.
python/.cspell.json	Adds codeact and hyperlight to dictionary.
docs/features/code_act/python-implementation.md	Adds Python-specific CodeAct design notes and API contract.
docs/features/code_act/dotnet-implementation.md	Adds placeholder for .NET CodeAct implementation notes.
docs/decisions/0024-codeact-integration.md	Adds ADR covering cross-SDK CodeAct integration approach and approval model.
.github/workflows/python-merge-tests.yml	Includes Hyperlight tests in “misc integration” selection.
.github/workflows/python-integration-tests.yml	Includes Hyperlight tests in “misc integration” job.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	415	52	87%	461, 470, 525, 1020, 1065, 1138–1142, 1205, 1233, 1270, 1291, 1311–1312, 1317, 1364, 1406, 1428, 1430, 1443, 1449, 1494, 1496, 1505–1510, 1515, 1517, 1523–1524, 1531, 1533–1534, 1542–1543, 1546–1548, 1558–1563, 1567, 1572, 1574
_sessions.py	273	30	89%	82–84, 86–89, 106–107, 109–113, 192–193, 283, 544–548, 590, 593, 627, 676, 680, 690, 823, 839
_tools.py	948	87	90%	191–192, 365, 367, 380, 405–407, 415, 433, 447, 454, 461, 484, 486, 493, 501, 540, 584, 588, 620–622, 630, 675–677, 679, 702, 728, 732, 770–772, 776, 798, 910–916, 952, 964, 966, 968, 971–974, 995, 999, 1003, 1017–1019, 1360, 1382, 1469–1475, 1604, 1608, 1654, 1715–1716, 1831, 1851, 1853, 1909, 1972, 2144–2145, 2165, 2221–2222, 2282, 2360–2361, 2428, 2433, 2440
packages/hyperlight/agent_framework_hyperlight
_execute_code_tool.py	399	79	80%	60, 94–97, 102, 116, 118, 131, 149, 159, 184, 189, 196, 202, 210, 218–220, 222–227, 250, 255, 257, 259, 272–281, 286–289, 297–298, 319–320, 330, 332, 360, 362, 388–389, 392, 396, 435–436, 508, 544, 550–552, 581–585, 589–590, 595, 612–616, 620–621, 677–678
_instructions.py	44	5	88%	14, 33, 45–46, 56
_provider.py	42	11	73%	53, 57, 65, 69, 73, 77, 81, 85, 89, 93, 97
_types.py	13	0	100%
TOTAL	27702	3278	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5450	20 💤	0 ❌	0 🔥	1m 26s ⏱️

[moonbox3]

This is a nice and complete ADR - well done. A lot here to unpack so doing a first pass with some questions.