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. |