nemo_gym.agent_utils.supervisor_client

Controller-side transport for the shared sandbox process supervisor.

Session ownership and cancellation live in sandbox_session.py; output parsing stays with the adapter. Unlike process_supervisor.py, this module is not uploaded to the task sandbox.

Session control files (all paths are relative to session_dir):

===================== ==================== =========================================== Filename Writer When ===================== ==================== =========================================== process_supervisor.py Session Uploaded before launch launch.claim Launch or stop shell Atomically claims launch or fences it supervisor.pid Launch shell After claiming launch, before exec stop.request Stop shell Before signalling the supervisor cleanup.json Supervisor or stop After cleanup, or when stop fences launch output.log Launch shell Captures supervisor and harness diagnostics ===================== ==================== ===========================================

Module Contents

Functions

Name	Description
`parse_cleanup_receipt`	Require positive cleanup evidence, tolerating malformed optional diagnostics.
`remove_session_directory`	Remove adapter-owned files after cleanup, keeping delayed launches fenced.
`stop_and_confirm_cleanup`	Fence a pending launch or require explicit supervisor acknowledgement before teardown.
`supervised_launch_command`	Fence delayed launches and run a harness command under the shared supervisor.
`supervision_timeouts`	Return the per-cleanup-phase and provider execution deadlines.

Data

CLEANUP_RECEIPT_FILE

SUPERVISOR_PID_FILE

_CLEANUP_RECEIPT

API

nemo_gym.agent_utils.supervisor_client.parse_cleanup_receipt(
    payload: object
) -> nemo_gym.agent_utils.process_supervisor.CleanupReceipt

Require positive cleanup evidence, tolerating malformed optional diagnostics.

nemo_gym.agent_utils.supervisor_client.remove_session_directory(
    sandbox: nemo_gym.sandbox.AsyncSandbox,
    session_dir: str,
    workdir: str | None,
    timeout: float,
    harness: str
) -> None

async

Remove adapter-owned files after cleanup, keeping delayed launches fenced.

Retire the directory atomically before unlinking its claim. Otherwise a delayed launch could win the claim while recursive deletion is in progress. A failed removal leaves the retired path available for a close retry.

nemo_gym.agent_utils.supervisor_client.stop_and_confirm_cleanup(
    sandbox: nemo_gym.sandbox.AsyncSandbox,
    session_dir: str,
    workdir: str | None,
    timeout: float,
    harness: str
) -> nemo_gym.agent_utils.process_supervisor.CleanupReceipt

async

Fence a pending launch or require explicit supervisor acknowledgement before teardown.

A stop that wins the launch claim writes the same receipt shape as the supervisor, with no return code because no harness process ran.

nemo_gym.agent_utils.supervisor_client.supervised_launch_command(
    session_dir: str,
    command: list[str],
    timeout: float,
    cleanup_timeout: float,
    python: str
) -> str

Fence delayed launches and run a harness command under the shared supervisor.

The adapter must install or select the interpreter explicitly. Check that it can load the supervisor before claiming a launch: a failed bootstrap cannot write a cleanup receipt. Supervisor and harness diagnostics share output.log.

nemo_gym.agent_utils.supervisor_client.supervision_timeouts(
    timeout: float,
    close_timeout: float
) -> tuple[float, float]

Return the per-cleanup-phase and provider execution deadlines.

Divide the close budget across TERM grace, harness process reaping, and descendant draining. The provider deadline reserves all three phases after the harness timeout, plus 30 seconds for startup, polling, and receipt I/O.

nemo_gym.agent_utils.supervisor_client.CLEANUP_RECEIPT_FILE = 'cleanup.json'

nemo_gym.agent_utils.supervisor_client.LAUNCH_CLAIM_FILE = 'launch.claim'

nemo_gym.agent_utils.supervisor_client.LOG = logging.getLogger(__name__)

nemo_gym.agent_utils.supervisor_client.OUTPUT_LOG_FILE = 'output.log'

nemo_gym.agent_utils.supervisor_client.STOP_REQUEST_FILE = 'stop.request'

nemo_gym.agent_utils.supervisor_client.SUPERVISOR_FILE = 'process_supervisor.py'

nemo_gym.agent_utils.supervisor_client.SUPERVISOR_PID_FILE = 'supervisor.pid'

nemo_gym.agent_utils.supervisor_client._CLEANUP_RECEIPT = TypeAdapter(CleanupReceipt)