nemo_gym.agent_utils.sandbox_session

Agent-server lifecycle for one supervised harness activation.

Module Contents

Classes

Name	Description
`SandboxCommand`	Harness argv and the installed interpreter used to launch its supervisor.
`SandboxSession`	Execute, stop, capture, then release an owned or borrowed sandbox.

Functions

Name	Description
`_reuse_or_start`	-

Data

LOG

API

class nemo_gym.agent_utils.sandbox_session.SandboxCommand(
    argv: list[str],
    python: str
)

Dataclass

Harness argv and the installed interpreter used to launch its supervisor.

argv

list[str]

python

str

class nemo_gym.agent_utils.sandbox_session.SandboxSession(
    sandbox: nemo_gym.sandbox.api.AsyncSandbox,
    session_dir: str,
    workdir: str | None,
    harness: str,
    owns_sandbox: bool = False
)

Dataclass

Execute, stop, capture, then release an owned or borrowed sandbox.

Runtime installation belongs in the adapter’s seed hook. stage_activation stages input and returns a command; collect copies harness artifacts to the agent server after cleanup is confirmed. It may run a bounded snapshot command, but must not restart the harness. Parsing responses stays in the adapter.

A new session stages input and its supervisor, runs the harness process, then stops and collects artifacts. Execution retains the sandbox until close releases it. A failed borrowed cleanup remains closing and can be retried; an owned sandbox can fall back to provider stop. Closed means release succeeded.

Each stop, collection and release phase is bounded by close_timeout (or the timeout passed to close). Failed cleanup/release retains the handle for retry. Failed capture is recorded separately and does not prevent release. HTTP request binding and activation retries belong to the agent session layer.

_capture_attempted

bool = field(default=False, init=False)

_close_task

Task[None] | None = field(default=None, init=False)

_collect

Callable[[], Awaitable[Artifacts]] | None = field(default=None, init=False)

_exec_task

Task[SandboxExecResult] | None = field(default=None, init=False)

_finalize_task

Task[None] | None = field(default=None, init=False)

_stage_task

Future[SandboxCommand] | None = field(default=None, init=False)

artifacts

Artifacts | None = field(default=None, init=False)

capture_error

Exception | None = field(default=None, init=False)

cleanup

CleanupReceipt | None = field(default=None, init=False)

closed

bool

Whether sandbox release completed successfully.

closing

bool

Whether close has been requested, including a failed attempt.

harness

str

launch_started

bool = field(default=False, init=False)

owns_sandbox

bool = False

sandbox

AsyncSandbox

sandbox_stopped

bool = field(default=False, init=False)

session_dir

str

stop_request_path

str

Marker path an adapter may pass to its harness for cancellation diagnostics.

workdir

str | None

nemo_gym.agent_utils.sandbox_session.SandboxSession._cancel_and_wait(
    task: asyncio.Future[nemo_gym.agent_utils.sandbox_session.SandboxSession._cancel_and_wait[T]],
    timeout: float
) -> None

async

nemo_gym.agent_utils.sandbox_session.SandboxSession._close(
    timeout: float
) -> None

async

nemo_gym.agent_utils.sandbox_session.SandboxSession._finalize(
    timeout: float
) -> None

async

nemo_gym.agent_utils.sandbox_session.SandboxSession._finish(
    timeout: float
) -> None

async

nemo_gym.agent_utils.sandbox_session.SandboxSession._release_exec(
    timeout: float
) -> None

async

nemo_gym.agent_utils.sandbox_session.SandboxSession._stage(
    stage_activation: collections.abc.Callable[[], collections.abc.Awaitable[nemo_gym.agent_utils.sandbox_session.SandboxCommand]]
) -> nemo_gym.agent_utils.sandbox_session.SandboxCommand

async

nemo_gym.agent_utils.sandbox_session.SandboxSession.close(
    timeout: float
) -> None

async

Join finalization before release; concurrent/retried closes never duplicate capture.

nemo_gym.agent_utils.sandbox_session.SandboxSession.execute(
    stage_activation: collections.abc.Callable[[], collections.abc.Awaitable[nemo_gym.agent_utils.sandbox_session.SandboxCommand]],
    collect: collections.abc.Callable[[], collections.abc.Awaitable[nemo_gym.agent_utils.sandbox_session.SandboxSession[Artifacts]]],
    timeout: float,
    close_timeout: float
) -> nemo_gym.agent_utils.sandbox_session.SandboxSession[Artifacts]

async

Run once, preserving captured artifacts even when execution raises.

Cancellation stops the remote harness before releasing provider exec. Callers that merely stop waiting (such as disconnected HTTP requests) must shield their shared activation task.

nemo_gym.agent_utils.sandbox_session.SandboxSession.read_output_log() -> str

async

Read combined supervisor/harness diagnostics without masking the original failure.

nemo_gym.agent_utils.sandbox_session.SandboxSession.stop_harness(
    timeout: float
) -> None

async

Fence a delayed launch or confirm descendant cleanup before transport cancellation.

nemo_gym.agent_utils.sandbox_session._reuse_or_start(
    task: asyncio.Task[nemo_gym.agent_utils.sandbox_session._reuse_or_start[T]] | None,
    factory: collections.abc.Callable[[], collections.abc.Coroutine[object, object, nemo_gym.agent_utils.sandbox_session._reuse_or_start[T]]]
) -> asyncio.Task[nemo_gym.agent_utils.sandbox_session._reuse_or_start[T]]

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