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
_tools.py	948	86	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, 2360–2361, 2428, 2433, 2440
packages/hyperlight/agent_framework_hyperlight
_execute_code_tool.py	477	85	82%	64, 100–101, 120, 122, 135, 153, 163, 188, 193, 200, 206, 214, 222–224, 226–231, 271, 276, 278, 280, 297–298, 307–310, 337–340, 346, 348, 358–359, 391–392, 395–396, 403, 431, 465–466, 472, 480–481, 484, 488, 499–505, 557–558, 584, 647, 683, 689–691, 720–724, 728–729, 734, 751–755, 759–760, 816–817
_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	28248	3300	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5621	30 💤	0 ❌	0 🔥	1m 31s ⏱️

[moonbox3]

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