[ffrujeri]

What changed

nemo_gym/server_runtime/episode_tokens.py adds EpisodeTokens, which mints and reads the credential an Environment Server grants for one episode's tools:

• mint(episode_id) returns a signed token and the EpisodeTokenClaims (episode ID and a random nonce) that the server keeps.
• read(token) returns the claims of a token this server signed, or None for anything else, including an MCP session token signed with the same key.
• EpisodeTokenClaims.matches compares the episode and the nonce in constant time.
• EPISODE_TOKEN_HEADER names the header that carries the token on a direct HTTP tool call.

Why

This is the first PR of a stack that lets an Environment Server own an episode's state and tools without a Resources Server (Linear GYMINT-641, under the design in the user-simulation RFC's layer 1, BaseEnvironmentServerWithTools). The tool calls arrive as separate requests, so they need a credential for the episode:

• A rollout ID is predictable: <task index>-<rollout index> unless the caller sets one, and the agent sees its own in its capture path. A bare ID would let a policy call another episode's tools, for example to read hidden knowledge without paying for it.
• A Gym server's signing key is derived from its class and instance names (SimpleServer.get_session_middleware_key), so a signature alone is forgeable.

The nonce makes the token unguessable; the server accepts it only while it holds the same claims. The signature keeps the claims intact, and lets a worker that does not hold the episode read which episode a token names, so a later PR can route the call to the worker that does.

Nothing uses the module yet; the next PR in the stack, the Environment Server base class that serves episode tools, does.

Validation

Command	Result
pytest tests/unit_tests/server_runtime/test_episode_tokens.py tests/unit_tests/test_import_linter_coverage.py (after the rebase onto main at dda609f86)	15 passed. The module is now nemo_gym/server_runtime/episode_tokens.py, next to the other server runtime modules
pytest tests/unit_tests/server_runtime/test_episode_tokens.py	11 passed: round trip with an attempt, a new nonce for each grant, another episode's token, a forged token with a guessed nonce, a tampered token, and six strings this server did not mint (another key, an MCP token with the same key, a missing nonce, an invalid episode, a payload that is not an object, garbage)
pre-commit run --files nemo_gym/server_runtime/episode_tokens.py tests/unit_tests/server_runtime/test_episode_tokens.py	passed

Rollout evidence

N/A: a library module that no server uses yet. The BIRD-Interact migration onto the Environment Server base class will run rollouts.

Compatibility

New module only. No existing behavior changes.

🤖 Generated with Claude Code

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

[ffrujeri]

/ok to test e050173

[ffrujeri]

/ok to test 3dc43be

[ffrujeri]

/ok to test fa0b016

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5346-fa0b01625c3c.docs.buildwithfern.com/nemo/gym

[ffrujeri]

/ok to test 8f232d4