harness.runner

A Runner is the compute backend that launches the FLARE agent container for a populated working directory. Each start() call returns an AgentRun handle that owns the lifecycle of the in-flight run.

Base

class milp_flare.harness.runner.base.Runner[source]

Launch the FLARE agent container for a populated working directory.

Attributes:
namestr

Compute backend identifier (e.g. "docker").

homestr

Absolute path of the container HOME for this backend.

imagestr

Image identifier for this runner.

abstractmethod start(wd, auth)[source]

Launch the agent with the given working directory and credentials.

Parameters:
wdpathlib.Path

The populated agent working directory.

authAuthSpec

Credential-forwarding spec from the harness.

Returns:
AgentRun

Handle to the in-flight run.

class milp_flare.harness.runner.base.AgentRun(start=None)[source]

Handle for a running agent, returned by Runner.start().

The handle owns the lifecycle of an active agent run. The caller is responsible for iterating stdout to retrieve agent output until the run ends (if stdout is not drained, the buffer will fill and block the agent). Use close() to stop the agent, capture any partial artifacts, and release the compute. Additionally, cancel() offers a thread-safe way to stop the agent without waiting for completion.

Attributes:
stdoutIterator[str]

Iterator yielding the agent’s stdout lines until the process exits (EOF).

duration_sfloat

Wall-clock duration of the run, in seconds. 0.0 until close() runs and sets it.

Returns:
AgentRun

Handle to the in-flight run.

abstractmethod cancel()[source]

Stop the agent process.

This does not capture partial artifacts or release compute. It solely stops the agent process and makes the stdout iteration end. This allows for thread-safe cancellation. Any consumer thread can detect cancellation by the end of the stream.

close()[source]

Stop the agent, capture partial artifacts, and release the compute.

duration_s = 0.0
class milp_flare.harness.runner.base.AuthSpec(env, home_dirs)[source]

Compute-agnostic description for forwarding agent credentials.

Attributes:
envlist[str]

Host environment-variable names to forward into the container.

home_dirslist[tuple[pathlib.Path, str]]

Host directories to make available under the container’s $HOME, as (host_dir, dest_basename) pairs (e.g. (~/.codex, ".codex")).

milp_flare.harness.runner.base.IMAGE = 'flare-agent:latest'

The default name of the Docker image containing the agent environment. This image is expected to be built prior to running FLARE. See Installation.

Docker

class milp_flare.harness.runner.docker.DockerRunner(image='flare-agent:latest')[source]

Bases: Runner

Run the agent in a local Docker container.

Parameters:
imagestr, default IMAGE

The Docker image tag to run. Built via milp-flare build-docker-image; see Docker.

class milp_flare.harness.runner.docker.DockerAgentRun(popen, name, stderr_f, start)[source]

Bases: AgentRun

Live handle for a single in-flight Docker agent run.

Parameters:
popensubprocess.Popen[str]

The Popen handle for the docker run running container process.

namestr

The unique container name for this run, used to target cancellation.

stderr_fIO[bytes]

The file where the container’s stderr is being redirected.

startfloat

The wall-clock time when the container was launched, for duration tracking.