feat(core): give stateful resources servers a teardown hook and an optional idle sweeper

[waple0820]

Closes #2609

/seed_session allocates a browser, container, sandbox or provider lease; nothing releases it. A rollout that fails, times out, is cancelled or loses its seed response leaves that resource alive, and a retry allocates another while the first stays unreachable.

Identity comes from the caller

The caller creates _ng_session_id before the first seed transmission, so the id survives a response that never arrives. The provider's own handle cannot serve here — it is learned from that response, which is exactly what goes missing. A separate _ng_session_close_token is stored only as a digest and authorizes releasing exactly that one session when the cookie is gone.

Seeding deduplicates

The transport may repeat a seed it is not sure was delivered.

• same id, same payload → the stored response is replayed, nothing is allocated
• same id, different payload → 409
• released id → 409, kept as a bounded tombstone

The last rule is not spelled out in the design. Replaying the stored response would hand the caller a session that no longer exists, so a released id is treated as spent.

The adapter owns everything that is not release

POST /close_session                    public route
_close_session_endpoint                identity, conflict checks, idempotency, response
release_session(session_id, reason)    release, and only release

The hook is deliberately not named close_session. GymnasiumServer, TALES and OpenAir already define that name with a different signature, and a base method sharing it would silently override theirs. Migration is one line, and is tested:

async def release_session(self, session_id, reason):
    await self.close_session(session_id)

We hit a version of that collision already: close_session as a typed POST route meant MCP auto-exposure published it as a model-callable tool, so a policy could have ended its own episode's resources.

Release runs once

The first closer creates the release task and concurrent closers await it, so provider cleanup does not run per caller. A failed release reports release_failed with 503 and leaves the session retryable rather than marking it closed.

An unknown id and an already-released one answer identically. There is no not_found status — that would let the endpoint be used to probe whether another rollout's session exists. This follows the close-session design rather than the five outcomes listed in #2609's body.

Expiry does not trust idle time alone

A rollout can sit in a model call for minutes without touching the resources server, so a session with handlers in flight is skipped. An absolute lifetime that activity does not suppress covers the case the first rule cannot: a handler that has hung. active_session() marks a handler in flight and refuses to start one once release has begun, so close cannot tear a resource down while verification is still reading it. The base uses it on its own routes; broad adoption across environment tool routes is #3037.

Scope

Agent-side orchestration, the bounded cancellation shield, X-NeMo-Gym-Cleanup-Status and the collector's _ng_run_info.cleanup are a follow-up, per "Agent and resources-server adoption are separate" in the design. The TTL mechanism stays here as the reference implementation; #3037 owns adoption across stateful servers.

Tests

27 cases over seven groups: seed replay does not allocate twice, payload conflict is 409, a delayed seed cannot resurrect a tombstone; the four terminal outcomes, a cookie/id conflict releasing neither, unknown and already-closed responses being byte-identical, ten concurrent closes releasing once, a failed release staying retryable; capability match, mismatch, id-alone rejection, and the token never reaching the record; idle expiry, busy suppression, absolute lifetime overriding busy, tombstone cleanup; handler counting and refusal after close; the base not defining close_session and the bridge working; route registration and release_session never reaching the model.

uv run --extra dev pytest tests/unit_tests -q → 4367 passed. test_e2b_provider and test_enroot_provider fail on a clean upstream/main too.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[waple0820]

Rebased onto main and out of draft.

Worth flagging what the rebase surfaced: six tests in responses_api_agents/simple_agent started failing, all of them asserting an exact POST sequence — /seed_session, /v1/responses, /verify — with no release at the end. session_scope() adds /close_session there, including on the skip-verification path from #2279. Updated those assertions rather than the behaviour: skipping the score does not skip the release.

One of the failures doubles as evidence for the design. When the release call itself fails, the episode logs

WARNING nemo_gym.base_responses_api_agent:217 failed to close the environment session on resources: ...

and returns its result normally. A reclaim that can break a rollout is worse than the leak it fixes, so the failure path is a warning by construction.

Also see #2750 (comment) on why a caller-driven release is necessary but not sufficient — the sweeper here is the part that survives a killed collector.

[waple0820]

#2886 landed yesterday — workplace_assistant now wraps its whole verify in a try/finally to drop the session's tool environment, including when scoring raises.

That is the same shape as interactive_browser in #1865 and the SWE agents' own paths, and all of them share one blind spot: the cleanup only runs when the episode reaches verify. An episode that times out, that crashes, or whose collector is killed never gets there, and whatever it allocated stays allocated.

That is what the hook here is for — the same guarantee in one place, plus the idle sweeper for the cases no call can reach.

[ananthsub]

The lifecycle hook, agent finally block, TTL sweeper, and tests remain useful, but #2609 now owns a stricter wire contract: caller-created session identity, one-session close capability, seed deduplication and conflict detection, dedicated close outcomes, and idempotent recovery after lost responses. #3037 owns generic TTL and server adoption. This PR should be refactored or replaced against #2609 rather than merged as the final API.