ProcessProgramExecutionEngine

Models & Types · AiDotNet.ProgramSynthesis.Execution

Runs an untrusted candidate program in an isolated, resource-limited child process.

Implements: IDisposable, IProgramExecutionEngine

For Beginners

When a language model writes a program, the only way to find out whether it works is to run it — and that is exactly the dangerous part, because nobody reviewed the code. This class runs it the careful way: in a separate process, in a throwaway folder, with a stopwatch, a memory ceiling, a limit on how much it may print, and with your environment variables hidden from it. If the program hangs, it and everything it started are killed. If it misbehaves, you get a result object describing what went wrong instead of an exception, so an evolution run simply scores that candidate poorly and carries on.

How It Works

This is the execution boundary the core library ships: it needs no container runtime, no network, and no extra package, only an interpreter or compiler already present on the machine and named by Interpreters. Each execution writes exactly one source file into a fresh workspace directory, launches the configured command with UseShellExecute off and all three standard streams redirected, and deletes the workspace afterwards — including after a timeout, a kill, or a crash.

Five limits are enforced rather than advertised. The child inherits a pinned PATH and a scrubbed environment, so it cannot resolve an executable from an attacker-controlled directory and cannot read the API keys, tokens, or connection strings held in the host’s environment. Standard output and standard error are drained concurrently into fixed-size buffers, so a program that prints without stopping is truncated and reported as truncated instead of exhausting host memory, and it never blocks on a full pipe. A wall-clock limit cancels the run and kills the whole process tree — Kill(entireProcessTree) where the framework offers it, with a taskkill /T /F fallback on Windows — so a detached grandchild cannot outlive its parent. Memory is capped by a Windows job object with a kill-on-close limit, or by ulimit -v inside a POSIX shell; CanEnforceMemoryLimit reports honestly when neither mechanism is available on this machine. A semaphore bounds how many executions run at once, and the wall-clock limit starts only after that semaphore is acquired, so a queued candidate is never charged for time it spent waiting.

Ordinary failure is never an exception. A program that will not compile, exits non-zero, times out, prints too much, or names a language with no configured interpreter comes back as a ProgramExecuteResponse carrying the matching ProgramExecuteErrorCode, because in an evolution run these outcomes are the common case and must simply score badly. A request that sets CompileOnly for a language with no separate compile command is refused outright rather than executed, since running code that the caller asked only to type-check is precisely the mistake this class exists to prevent.

Constructors

Constructor Summary
ProcessProgramExecutionEngine(ProgramSandboxOptions options) Initializes an engine bound to a validated copy of the supplied sandbox options.

Properties

Property Summary
bool CanEnforceMemoryLimit { get; } Gets whether this machine can enforce the configured memory limit on a sandboxed child.

Methods

Method Summary
ProgramSandboxOptions GetOptions() Gets the sandbox options this engine was constructed with.
Task<ProgramExecuteResponse> ExecuteAsync(ProgramExecuteRequest request, CancellationToken cancellationToken)
bool TryExecute(ProgramLanguage language, string sourceCode, string input, string output, string errorMessage, CancellationToken cancellationToken)
void Dispose() Releases the concurrency semaphore held by this engine.