.NET: Python: feat(python): Add local-codeact package with AST validation

[eavanvalkenburg]

Add agent-framework-local-codeact alpha package with AST validation for Foundry hosted agents

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/local_codeact/agent_framework_local_codeact
_bridge.py	196	54	72%	26, 30, 37–42, 54, 63, 73–75, 82, 133, 146–147, 150–152, 154, 163, 168–171, 175, 180, 183, 190, 200–201, 211–214, 218, 222–224, 243–245, 253–254, 261–262, 276–279, 281–282, 293
_execute_code_tool.py	223	38	82%	56, 58, 84, 86, 89, 101, 109, 114, 116, 118, 126–127, 129, 145, 148, 151–154, 156, 161–162, 166, 229, 246–248, 285, 298–301, 305, 310, 315, 395–396, 438
_files.py	120	34	71%	23, 27, 29, 37, 45–49, 70, 87–88, 94, 97–98, 106, 110–115, 131, 138–139, 143, 146–147, 149–150, 152–153, 156–157
_instructions.py	38	15	60%	16, 35, 41–45, 47–50, 55, 110–111, 113
_provider.py	34	8	76%	81, 85, 89, 93, 97, 101, 105, 109
_runner.py	123	96	21%	21–24, 27, 30–37, 40, 44, 48, 52–60, 64–70, 72, 74–75, 89–91, 95–96, 100–113, 117–118, 120–121, 131–133, 142–143, 147–151, 154, 156–157, 159, 164–166, 168–171, 173, 184–197, 206, 210
_types.py	22	0	100%
_validator.py	76	10	86%	271–272, 286–287, 303–304, 308, 310, 337, 427
TOTAL	37668	4594	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7403	34 💤	0 ❌	0 🔥	1m 57s ⏱️

[Copilot]

Pull request overview

Adds a new alpha Python workspace package, agent-framework-local-codeact, intended to enable CodeAct-style execution of model-generated Python in externally sandboxed environments (e.g., Foundry hosted agents), with subprocess execution, file-mount capture, and AST-based validation.

Changes:

• Registers agent-framework-local-codeact in the Python workspace (uv/pyproject) and marks it as alpha in PACKAGE_STATUS.md.
• Introduces LocalExecuteCodeTool / LocalCodeActProvider with subprocess runner + IPC bridge, file-mount capture helpers, and dynamic instructions.
• Adds unit tests plus usage samples and package documentation.

Reviewed changes

Copilot reviewed 20 out of 22 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
python/uv.lock	Adds the new editable workspace member and lock metadata.
python/pyproject.toml	Registers the new workspace package.
python/PACKAGE_STATUS.md	Marks agent-framework-local-codeact as alpha.
python/packages/local_codeact/pyproject.toml	New package definition, tooling config, and test tasks.
python/packages/local_codeact/README.md	Package docs, security posture, and configuration surface.
python/packages/local_codeact/AGENTS.md	Package architecture and contributor notes.
python/packages/local_codeact/LICENSE	MIT license for the new package.
python/packages/local_codeact/agent_framework_local_codeact/init.py	Public API exports for the package.
python/packages/local_codeact/agent_framework_local_codeact/_types.py	Public types for execution mode, mounts, and limits.
python/packages/local_codeact/agent_framework_local_codeact/_validator.py	AST-based code validation layer.
python/packages/local_codeact/agent_framework_local_codeact/_bridge.py	Parent-side subprocess bridge + tool dispatch.
python/packages/local_codeact/agent_framework_local_codeact/_runner.py	Child-process runner implementing the JSON-lines protocol.
python/packages/local_codeact/agent_framework_local_codeact/_files.py	Mount normalization + symlink-safe file capture.
python/packages/local_codeact/agent_framework_local_codeact/_instructions.py	Dynamic CodeAct instructions and tool descriptions.
python/packages/local_codeact/agent_framework_local_codeact/_execute_code_tool.py	Main execute_code tool orchestration and output shaping.
python/packages/local_codeact/agent_framework_local_codeact/_provider.py	Context provider that injects the run-scoped tool + instructions.
python/packages/local_codeact/tests/local_codeact/test_validator.py	Validator allow/block behavior tests.
python/packages/local_codeact/tests/local_codeact/test_local_codeact.py	Tool/provider behavior, subprocess execution, mounts, and limits tests.
python/packages/local_codeact/samples/README.md	Sample index and run instructions.
python/packages/local_codeact/samples/local_execute_code.py	Local usage sample for direct tool invocation.
python/packages/local_codeact/samples/foundry_hosted_agent.py	Foundry hosted-agent wiring sample.
python/packages/local_codeact/agent_framework_local_codeact/py.typed	Marks the package as typed.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 88%

✓ Correctness

After thorough examination of the local-codeact package implementation, I found no correctness bugs. The code demonstrates excellent engineering practices: proper error handling with early validation, safe resource cleanup using try-finally blocks and context managers, correct subprocess management with timeout handling, secure AST validation with comprehensive allow/block lists, and proper IPC serialization with JSON-safe conversions. All test assertions correctly match the implementation behavior. The Windows environment variable handling (SYSTEMROOT, COMSPEC, PATHEXT) is intentional and necessary for subprocess creation. The validator's permissive approach to user-defined functions is documented and tested. Edge cases like subprocess death, tool call failures, timeout during execution, and symlink handling are all properly managed.

✓ Security Reliability

The local CodeAct package provides defense-in-depth controls for executing LLM-generated Python code, with AST validation, subprocess isolation, and explicit environment control. The implementation is generally sound for its stated purpose (use in external sandboxes like Foundry). However, there are three reliability concerns: (1) the AST validator allows 'open' in ALLOWED_BUILTINS while blocking it in BLOCKED_BUILTINS, creating conflicting policy; (2) subprocess environment building on Windows includes parent environment keys that could leak sensitive data; (3) the validator allows delattr/setattr which could modify object internals unsafely. The package correctly disclaims being a security sandbox and documents required external isolation.

✓ Test Coverage

The test suite provides solid coverage of core functionality (subprocess execution, tool calling, validation, file capture, environment isolation). However, several edge cases and error paths lack coverage: (1) invalid input validation for constructors (empty/invalid paths, negative limits), (2) error handling for subprocess failures (invalid Python executable, runner script errors, malformed bridge responses), (3) boundary conditions for limits (exact limit sizes, total capture limits), (4) file mount edge cases (duplicate mounts, overlapping paths, permission errors), (5) race conditions in async tool calls, and (6) error recovery paths in the bridge protocol. The existing tests are well-structured and verify the happy paths thoroughly.

✓ Design Approach

The design approach is sound for the stated goal of adding AST-validated local code execution for Foundry hosted agents. The validation correctly runs before all execution paths, the subprocess bridge properly serializes concurrent tool calls via async locks, symlink handling prevents directory traversal, and the custom allow/block list semantics are clearly documented. All test cases in the diff are consistent with the implementation.

---

Automated review by eavanvalkenburg's agents

[eavanvalkenburg]

Review Comments Addressed

All 8 review comments have been addressed in commit a38ea7c:

Security Fixes

1. ✅ Removed dangerous builtins from ALLOWED_BUILTINS: open, getattr, setattr, hasattr removed as they bypass AST attribute restrictions
2. ✅ Added to BLOCKED_BUILTINS: getattr, setattr, hasattr, delattr now explicitly blocked with explanatory comments

Implementation Fixes

3. ✅ create_run_tool propagation: Now propagates allowed_imports, blocked_imports, allowed_builtins, blocked_builtins to run-scoped tool
4. ✅ Subprocess leak fix: Added await self._stop_process(process) before raising on error messages
5. ✅ allowed_builtins behavior documented: Added docstring explaining that we only enforce block-list (not allow-list) for builtins to permit user-defined functions and registered tools

Sample Fixes

6. ✅ Module docstrings moved: Moved module docstrings to file start in both samples
7. ✅ Pointless strings removed: Removed trailing sample output string statements that triggered B018

All checks passing locally:

• uv run poe check-packages -P local_codeact ✅
• uv run poe mypy -P local_codeact ✅
• uv run poe test -P local_codeact ✅ (46 tests)

[eavanvalkenburg]

Python 3.10 Compatibility Fixed

Fixed timeout test that was failing on Python 3.10 due to different TimeoutError string representation.

Commit: 4760db8

Verified on:

• Python 3.10.15 ✅
• Python 3.12.7 ✅

All 46 tests now pass on both versions.