.NET: feat(dotnet): Add LocalCodeAct package for local Python execution

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation and Context

Microsoft Foundry hosted agents are already container-isolated, but agent code today has no way to let an LLM author and run Python in-process inside that sandbox. This PR adds a CodeAct provider for .NET that complements the existing Hyperlight and Monty providers with an in-process Python subprocess option, intended for hosts that have already established their own isolation boundary (Foundry hosted agents, Container Apps, dedicated VMs).

This is the .NET counterpart of the Python agent-framework-local-codeact package (PR #6091); both packages share the same Python validator/runner scripts so behavior stays aligned across languages.

Description

Adds a new Microsoft.Agents.AI.LocalCodeAct package plus a unit-test project and two samples.

Package (dotnet/src/Microsoft.Agents.AI.LocalCodeAct):

• LocalCodeActProvider — AIContextProvider that injects an execute_code AIFunction and per-run system instructions describing host tools and mounts.
• LocalCodeActProviderOptions — approval mode, host tools, file mounts, execution limits, environment, Python executable/runner overrides, and allow/block-list overrides for imports/builtins.
• LocalExecuteCodeFunction (via Internal/ExecuteCodeFunction) — the execute_code tool surface invoked by the model.
• Internal/ProcessBridge — JSON-lines IPC between host and Python subprocess (request framing, tool callbacks, response parsing, timeouts).
• Internal/CodeExecutor — orchestrates validation → subprocess execution → captured-file collection.
• Internal/CodeValidator — invokes the embedded Python validator via stdin JSON and converts errors to CodeValidationException.
• Internal/FileMountHelper — normalizes mount paths, snapshots writable mounts before execution, and captures new/modified files after.
• Internal/InstructionBuilder — renders system instructions that document the tool surface, mounts, and policy.
• FileMount, ProcessExecutionLimits, LocalCodeActProviderOptions, CodeValidationException — public types.
• Resources/runner.py, Resources/validator.py — embedded Python scripts kept in sync with the Python package; the validator script is identical apart from a _main() stdin entrypoint used by the .NET host.

Tests (dotnet/tests/Microsoft.Agents.AI.LocalCodeAct.UnitTests):
18 tests covering option validation, instruction-builder output, file-mount normalization, capture limits, provider wiring, and end-to-end Python subprocess integration (LocalExecuteCodeFunctionIntegrationTests).

Samples:

• dotnet/samples/GettingStarted/AgentProviders/LocalCodeAct — minimal getting-started console sample.
• dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct — Foundry hosted-agent sample with Compute and FetchData tools (mirrors the Python foundry_hosted_agent sample and the existing Hosted-LocalTools layout). Includes Program.cs, HostedLocalCodeAct.csproj, agent.yaml, agent.manifest.yaml, Dockerfile + Dockerfile.contributor (install Python 3 and set LOCAL_CODEACT_PYTHON=python3), .env.example, and a README with the standard run/curl flow.

Validation policy:

• AST allow-list for imports and builtins (replaceable per call).
• os.* attribute allow-list of {environ, path} only; every other os.<attr> is rejected. Override via the validator's allowed_os_attrs JSON field.
• Captured files only come from read-write mounts; the capture helpers skip symlinks and hardlinks and verify that every entry's resolved path stays under the mount root, so a virtual mount path cannot be redirected (via symlink, hardlink, junction, or ..) to data outside its host directory.

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? No

Related: companion Python PR #6091.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 91%

✓ Correctness

This PR has several critical correctness bugs: (1) ProcessBridge deserializes JSON to Dictionary<string, object?> which yields JsonElement values, then uses as Dictionary<string, object?> and Convert.ToInt32() casts that always fail, silently discarding subprocess results and crashing tool calls; (2) LocalCodeActProvider overides a non-existent ProvideContextAsync method instead of the actual base class method ProvideAIContextAsync(InvokingContext, CancellationToken) with incompatible signature and return type; (3) The runner script path is incorrectly passed as the validator script path to CodeValidator; (4) validator.py has no __main__ entry point, so AST validation always passes without actually validating.

✓ Security Reliability

The PR introduces a local Python code execution package with critical security and reliability issues: (1) the runnerScript parameter is incorrectly passed to CodeValidator as the validatorScript, which means if a custom runner script is configured alongside validation lists, the validation step will execute the code instead of validating it; (2) the CodeValidator subprocess has no timeout, creating a potential hang/DoS vector; (3) the _call_tool in runner.py uses id(kwargs) as call_id which can produce 64-bit integers that would overflow when the .NET side uses Convert.ToInt32.

✓ Test Coverage

The test suite covers only construction, metadata, and default values for 3 of the 5 production classes. There are no tests for the core behavior: LocalCodeActProvider.ProvideContextAsync (tool injection and disposal guard), LocalExecuteCodeFunction.InvokeCoreAsync (argument validation, post-dispose exception), CodeValidator.ValidateAsync, or ProcessBridge.RunAsync. The PR rationale acknowledges 'Full execution tests require Python installed and will be added in follow-up,' but several behavioral tests are achievable without Python (e.g., ProvideContextAsync output, InvokeCoreAsync missing 'code' argument, ObjectDisposedException after dispose, CodeValidator construction). Given this is marked as having 'remaining work' for additional tests, these are suggestions rather than blocking issues.

✗ Design Approach

The overall package shape matches the intended CodeAct surface, but I found three design-level blockers in the execution path: the default runner path cannot launch the bundled runner, successful subprocess results are silently discarded when parsed back into .NET, and the default constructor bypasses AST validation even though the package README documents validation as the default behavior.

Flagged Issues

• ProcessBridge.cs:46 — the default path invokes python -m agent_framework_local_codeact._runner, but the runner is only shipped as an embedded .NET resource with no extraction logic (unlike CodeValidator which extracts its embedded script). Default construction always fails with ModuleNotFoundError.
• ProcessBridge.cs:128-151 — JsonSerializer.Deserialize<Dictionary<string, object?>> materializes nested JSON as boxed JsonElement values. The as Dictionary<string, object?> cast always returns null, silently discarding all subprocess stdout/stderr/output on every successful execution.
• LocalExecuteCodeFunction.cs:71-80 — CodeValidator is only instantiated when custom allow/block lists are supplied, contradicting README.md:91 which documents validation as the default behavior. The default constructor path runs unvalidated Python.

---

Automated review by eavanvalkenburg's agents

[Copilot]

Pull request overview

Adds a new .NET package (Microsoft.Agents.AI.LocalCodeAct) intended to run LLM-generated Python in a local subprocess with JSON-lines IPC, plus unit tests and a sample showing basic wiring.

Changes:

• Introduces a new LocalCodeAct implementation (provider + execute_code function) with embedded Python runner/validator resources.
• Adds initial unit test project covering basic construction/metadata/defaults.
• Adds a new sample project and README documentation for usage and configuration.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Microsoft.Agents.AI.LocalCodeAct.csproj	New packable project; embeds Resources/*.py and exposes internals to tests.
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/ProcessBridge.cs	Parent-side subprocess IPC bridge + tool dispatch (currently has critical JSON/type and runner-resolution issues).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/CodeValidator.cs	.NET wrapper intended to run embedded Python AST validator (currently mismatched with validator script behavior).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/LocalExecuteCodeFunction.cs	execute_code tool implementation (currently mismatched with repo’s AIFunction API and validation wiring).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/LocalCodeActProvider.cs	AIContextProvider integration (currently overrides a non-existent method in this repo).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/ProcessExecutionLimits.cs	Resource limit record (timeout/stdout/stderr/file size limits).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/FileMount.cs	File mount type definitions (host path + logical mount path + mode).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/ExecutionMode.cs	ExecutionMode enum (Subprocess-only).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Resources/runner.py	Embedded Python child runner implementing JSON-lines protocol + tool calls.
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Resources/validator.py	Embedded AST validator (currently missing CLI/stdio protocol entrypoint).
dotnet/src/Microsoft.Agents.AI.LocalCodeAct/README.md	Package documentation and examples (currently diverges from actual API/behavior).
dotnet/tests/Microsoft.Agents.AI.LocalCodeAct.UnitTests/Microsoft.Agents.AI.LocalCodeAct.UnitTests.csproj	New unit test project referencing the new package.
dotnet/tests/Microsoft.Agents.AI.LocalCodeAct.UnitTests/LocalExecuteCodeFunctionTests.cs	Basic tests for construction/metadata/disposal (currently missing using System;).
dotnet/tests/Microsoft.Agents.AI.LocalCodeAct.UnitTests/ProcessExecutionLimitsTests.cs	Tests for default/custom limit values.
dotnet/tests/Microsoft.Agents.AI.LocalCodeAct.UnitTests/FileMountTests.cs	Tests for FileMount defaults/customization.
dotnet/samples/LocalCodeAct/LocalCodeAct.csproj	New sample project referencing LocalCodeAct + core agent project.
dotnet/samples/LocalCodeAct/Program.cs	Sample demonstrating provider/function instantiation (currently missing using System / System.Threading.Tasks).
dotnet/samples/LocalCodeAct/README.md	Sample README with safety guidance and run instructions.

[Eduard van Valkenburg (eavanvalkenburg)]

File Mount Support and Integration Tests Added

Commit: fad8409

New Features

1. FileMountHelper.cs (310 lines)

   • NormalizeMountPath() - POSIX path normalization with validation
   • ResolveExistingDirectory() - directory existence verification
   • IterRealFiles() - recursive file walking (skips symlinks)
   • SnapshotWritableMounts() - pre-execution file state capture
   • CaptureWrittenFiles() - post-execution file diff and content extraction
   • Media type detection for common file extensions

2. Updated LocalExecuteCodeFunction

   • Added fileMounts parameter
   • Snapshots writable mounts before execution
   • Captures written files after execution
   • Returns captured files as AIContent in results

3. Updated LocalCodeActProvider

   • Added fileMounts parameter pass-through

4. IntegrationTests.cs (10 test cases)

   • ✅ Execute simple code and return result
   • ✅ Execute code with timeout (throws exception)
   • ✅ Execute code with invalid syntax (returns error)
   • ✅ Execute code with blocked import (validation fails)
   • ✅ Execute code with blocked builtin (validation fails)
   • ✅ Execute code with custom allowed imports
   • ✅ Execute code with file mounts (read from /input, write to /output, capture files)
   • ✅ Execute code with stdout capture
   • ✅ Provider injects tool into context

Implementation Parity

All features from Python agent-framework-local-codeact are now implemented in .NET:

• ✅ AST validation with custom allow/block lists
• ✅ Subprocess execution with JSON-lines IPC
• ✅ Process execution limits (timeout, stdout/stderr caps, result size)
• ✅ File mount support (read-only, read-write, overlay)
• ✅ File capture with per-mount and total limits
• ✅ Symlink-safe file walking
• ✅ Tool injection and CodeAct instructions
• ✅ Comprehensive integration tests

Note: Tests are marked to skip when Python is not available, allowing the package to build and basic tests to pass even without Python installed.