Skip to content

feat(core): session secrets, cookie names and MCP endpoint options for servers that sandboxed code calls - #6161

Open
d-molinari wants to merge 2 commits into
mainfrom
dmolinari/session-secret-and-mcp-endpoint-options
Open

d-molinari wants to merge 2 commits into
mainfrom
dmolinari/session-secret-and-mcp-endpoint-options

Conversation

@d-molinari

@d-molinari d-molinari commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Lets a server that code in a sandbox calls keep its sessions and its MCP endpoint to itself. It is the first of three pieces that #5010's review split out: this one, then single_agent_turn's step loop (#6162, built on this branch), then OfficeEnv's sandboxed server (#5010, built on that one). Every option is off by default, and the defaults are today's behavior.

  • SimpleServer.get_session_secret() is the key that signs session cookies and MCP session tokens, and session routing reads both with it. Its default is today's key, get_session_middleware_key(). The docstring says what an override must keep: one secret in every worker, and a secret that changes ends every open session.
  • SimpleServer.get_session_cookie_name() is the session cookie's name (default: the same key).
  • mcp_server_name on BaseResourcesServerConfig is the name the MCP endpoint lists itself under in the seed's MCP metadata. Clients name its tools mcp__<name>__<tool>, and verify-time normalization strips that namespace.
  • mcp_bearer_token hands out the session token as Authorization: Bearer. tools/list then needs a token and lists only the session's tools, a tool outside the grant is answered as an unknown tool, and errors name no framework.
  • Both options are refused without expose_tools_over_mcp. mcp_server_name must be a name an MCP grant takes (MCP_TOOL_ACCESS_NAME_PATTERN, which starts with a letter or digit) and fit MCP's tool-name alphabet. A single_agent_turn pairing that grants two MCP endpoints listed under one name does not start, since their tools would collide; the check is per pairing, so two servers in one run may share a name when no episode is granted both.
  • mcp_bearer_token refuses to start while the server signs its tokens with the default key: that key is public (the default cookie name shows it), so code that reads one token could sign another session's. A server that sets the option overrides get_session_secret().
  • The legacy sandbox seeder (seed_mcp_servers) lists each tool server under the name its endpoint advertises, so the sandboxed Pi and OpenCode agents name its tools that way; two servers advertising one name are refused.

Validation

On main a57f9cd437:

  • Gym's core suite, as CI runs it (four shards, then -m sandbox): all four shards and the 1,820 sandbox tests pass; combined core coverage 95.18%.
  • gym env test: environment_servers/single_agent_turn 299 passed, responses_api_agents/pi_sandboxed_agent 63 passed, responses_api_agents/opencode_sandboxed_agent 173 passed (its 2 Node tests skip without Node; they pass with it).
  • The new tests fail on the code they guard: tokens read with the public key, run_webserver handing session routing Gym's own header or key, the options without the endpoint, two endpoints under one name, a name no grant takes, a bearer token signed with the default key, and the seeder's advertised names.
  • pre-commit passes on the changed files, detect-secrets flags only test values in them, and every commit is signed off.

Checklist

  • I have read the contributing guidelines.
  • The change is focused; unrelated "drive-by" edits are tracked as separate issues/PRs.
  • Tests added or updated and pass locally, or N/A for docs-only / non-code changes (so CI unit/server checks pass when applicable).
  • Documentation added or updated, or N/A with justification (the MCP resources-server tutorial; single_agent_turn's README).
  • Pre-commit checks pass locally, on the changed files (so CI lint/format checks pass).
  • New source files include the required Apache-2.0 SPDX header.
  • All commits have DCO sign-off (git commit -s) (so the DCO check passes).

🤖 Generated with Claude Code

@copy-pr-bot

copy-pr-bot Bot commented Nov 13, 2026

Copy link
Copy Markdown

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.

@d-molinari

Copy link
Copy Markdown
Contributor Author

/ok to test d60160b

@nemo-automation-bot
nemo-automation-bot Bot requested review from a team November 13, 2026 19:30
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

@svcnvidia-nemo-ci svcnvidia-nemo-ci left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHIP WITH CARE

Two RISK findings affect the new mcp_server_name option: some accepted names fail during agent seeding, and the shared legacy sandbox seeder ignores the advertised name.

I reviewed all 13 changed files and traced the affected signing, routing, checkpoint, grant, and agent-consumer paths. One delegated report wasn't available, so I completed that topic's source inspection directly. This was a static review; I didn't execute tests or model rollouts, and the PR's validation results remain author-reported.


Inline comments (escaped v1):

  • nemo_gym/server_runtime/tool_access.py line 47: RISK — Accept the new endpoint names in the MCP grant contract

    With expose_tools_over_mcp: true and mcp_server_name: _company, the new configuration field validates, but a single_agent_turn episode granting those tools fails before agent seeding. _mcp_tool_access copies the advertised name into this field, whose pattern rejects a leading _ or -. Every episode using either newly accepted leading character fails instead of carrying the advertised name unchanged.

    Could you align this consumer with the endpoint's supported alphabet? At this field, the small correction is:

        name: str = Field(min_length=1, pattern=r"^[A-Za-z0-9_-][A-Za-z0-9._-]*$")
    

    This preserves existing alphanumeric names and interior dots while accepting the new leading characters. Keep DirectHTTPToolAccess unchanged, and retain rejection of empty names and leading dots. The inspected OpenCode consumer uses the name unchanged as its configuration key; Codex's name predicate also permits these characters.

    Proposed checks, not executed: parameterize the metadata-to-grant test with _company, -company, and company; each episode should reach agent seeding with that exact name and unchanged Authorization header. Add contract assertions that company.tools remains accepted while '' and .company remain rejected. Retain the collision cases: equal names on two granted MCP endpoints fail, but direct-HTTP-only Resources access causes no MCP-name collision. Verify the suggested code before adopting it.

  • nemo_gym/agents/agent_tools.py line 67: RISK — Honor the advertised name in the shared sandbox seeder

    The new option changes seed metadata's server_name, but seed_mcp_servers still keys each client configuration entry by the deployment reference. For example, a tool server referenced as store with mcp_server_name: company produces an entry named store, not company. PiSandboxedAgent passes these entries into its MCP configuration, and the adapter constructs tool names from those keys, so the model still sees store_append rather than company_append. The legacy OpenCode path uses the same helper. These sandbox callers therefore ignore the new identity option.

    Could you use the metadata name for the client entry while retaining the deployment reference for HTTP routing? Immediately before constructing the entry here, a suggested correction is:

    listed_as = metadata.get("server_name") or server.name
    if listed_as in entries:
        raise ValueError(f"Tool servers advertise the same MCP name {listed_as!r}")
    entries[listed_as] = {
        # Keep the existing URL, headers, enabled, and timeout fields.
    }

    The dependent OpenCode change is required: its required-server environment variable must use the same effective entry keys, or the required-server check will reject the renamed connection. Before building that command, derive them as:

    rollout_mcp = getattr(request.state, "_ng_opencode_mcp", None)
    required_mcp_names = (
        list(rollout_mcp)
        if isinstance(rollout_mcp, dict)
        else [s.name for s in self.config.tool_servers]
    )

    Then serialize required_mcp_names in the environment variable. Keep sandbox_server_url(server.name, ...), deployment lookups, and network routing on the real server reference. Preserve the old name when metadata omits server_name, unchanged headers/timeouts, and existing static-config precedence. Reject duplicate advertised names within one seeded set rather than silently overwriting an endpoint; separate episodes may still reuse a name.

    Proposed checks, not executed: stub a seed reply with server_name='company', URL path /mcp, and Authorization: Bearer scoped. Seeding reference store should return only key company, with the URL still resolved through store and the header unchanged. Without server_name, expect key store. Two references advertising company should fail explicitly. Check that Pi's generated configuration uses company, and OpenCode's configuration and required-server list both use company. Retain the per-run configuration test's assertions that credentials stay out of the receipt and the static configuration remains unchanged. Verify these suggestions before adopting them.

Review generated by codex. This was a full review. Request a full review with /review reset=true.

@cmunley1 cmunley1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall. With every option off the behavior matches today (same header, key and cookie name, same error text), and the new tests fail when the guarded lines are broken.

RISK: mcp_bearer_token with the default session secret (base_resources_server.py:186, base_server.py:348)
The default get_session_secret() is the public Class___name string, which is also the default cookie name, so it shows up in every Set-Cookie header. With mcp_bearer_token: true and no override, sandboxed code can sign {"sid": <another session>, "tools": null} and get every tool on another session, which is the per-session grant this option exists to enforce.
Suggest refusing the config at startup when mcp_bearer_token is on and get_session_secret() == get_session_middleware_key().

NOTE: tokens never expire (base_resources_server.py:104)
URLSafeSerializer has no timestamp, so only the session fence ends a token. This was already true on main, but this PR is the one that hands tokens to code the model can read. URLSafeTimedSerializer with max_age on load would close it.

@yaoyu-33
yaoyu-33 requested review from gchlebus and removed request for sephmard November 16, 2026 00:16
@svcnvidia-nemo-ci svcnvidia-nemo-ci added feature New capabilities, enhancements, or enablement work area:core Shared APIs, servers, telemetry, health, and registries needs-review PR is ready for code review and waiting on a reviewer labels Nov 16, 2026
@github-actions github-actions Bot added the sla:review-overdue Review response is over the one-business-day SLA label Nov 16, 2026
@d-molinari
d-molinari force-pushed the dmolinari/session-secret-and-mcp-endpoint-options branch from 40a158b to 2efe9fd Compare November 17, 2026 01:40
@d-molinari

Copy link
Copy Markdown
Contributor Author

Thanks, both. Fixed in 2efe9fd, and the branch is now rebased onto main (4e3f503):

  • Bot, grant names: fixed on the producer side. mcp_server_name must now match MCP_TOOL_ACCESS_NAME_PATTERN, the MCP grant's own pattern (one constant), on top of MCP's tool-name alphabet. _company, -company and .company are refused at config, and the grant contract is unchanged. A dot stays refused in mcp_server_name, because Pi's MCP adapter and Codex reject it in a server name.
  • Bot, legacy seeder: seed_mcp_servers keys each entry by the advertised server_name (else the reference) and refuses two servers that advertise one name. URL resolution and headers still follow the reference. OpenCode's required-server list uses the same keys; Pi needed no change. The tests cover each case you listed.
  • cmunley1, bearer tokens with the default secret: good catch. Exposure now refuses mcp_bearer_token while get_session_secret() returns the public session middleware key, and the error names the override. OfficeEnv's sandboxed server (feat(officeenv): run OfficeEnv episodes in a sandbox, for Gym's sandboxed harnesses #5010) already overrides it.
  • cmunley1, token expiry: this is true on main too. Today a closed session's fence ends its tokens. A timed token needs a max age longer than the longest episode, so I'd rather do it in its own PR than here.
  • Rebase: main's Environment Server tools now serve MCP through mount_mcp_endpoint (feat(environment): serve BaseEnvironmentServerWithTools episode tools over MCP #5349), and resources servers' auto-exposure mounts through it too, under the advertised mcp_server_name. Main's header sessions (feat(environment): route BaseEnvironmentServerWithTools tool calls to the worker that runs the episode #5350) and this PR's bearer-token reader both stay in session routing.

@d-molinari

Copy link
Copy Markdown
Contributor Author

/ok to test 2efe9fd

@nemo-automation-bot
nemo-automation-bot Bot requested a review from a team November 17, 2026 01:55
@yaoyu-33
yaoyu-33 requested a review from lafrancef November 17, 2026 02:05
d-molinari and others added 2 commits November 18, 2026 13:41
…r servers that sandboxed code calls

A resources server that lends a sandbox is reached by code the model controls, so the session key that every
caller can compute from the server's class and name must not sign its cookies and MCP tokens, and its endpoint
should look like an ordinary one.

- SimpleServer.get_session_secret() signs session cookies and MCP session tokens (default: the session middleware
  key, so nothing changes). Session routing reads cookies and tokens with it. Its docstring states what an
  override must keep: one secret in every worker, and a secret that changes ends every open session.
- SimpleServer.get_session_cookie_name() names the session cookie (default: the same key).
- mcp_server_name: the name the MCP endpoint lists itself under; verify-time normalization strips its namespace.
- mcp_bearer_token: tokens ride as Authorization: Bearer, tools/list needs one and lists only the session's tools,
  a tool outside the grant is an unknown tool, and errors name no framework.
- Both options are refused without expose_tools_over_mcp, and a name outside MCP's tool-name alphabet is refused.
  A single_agent_turn pairing refuses to grant two MCP endpoints listed under one name.

Signed-off-by: Daniele Molinari <dmolinari@nvidia.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…er tokens without a secret

Review fixes for the MCP endpoint options.

- mcp_server_name is also checked against the name pattern of an MCP grant (MCP_TOOL_ACCESS_NAME_PATTERN in
  tool_access, which MCPToolAccess uses), so a name that an Environment Server cannot grant, one that starts with
  '_' or '-', is refused at config instead of failing every episode before the agent seed. The grant contract is
  unchanged. A dot stays refused: Pi's MCP adapter and Codex refuse server names outside [A-Za-z0-9_-].
- seed_mcp_servers keys each entry by the seed metadata's server_name, else the server's name, and refuses two
  servers listed under one name. URLs, headers and routing still use the server's reference. The sandboxed
  OpenCode agent's required-server list uses the same keys; the sandboxed Pi agent reads them as given.
- An MCP endpoint with mcp_bearer_token refuses to start while get_session_secret() is the public session
  middleware key, since code that reads one bearer token could sign another session's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Daniele Molinari <dmolinari@nvidia.com>
@d-molinari
d-molinari force-pushed the dmolinari/session-secret-and-mcp-endpoint-options branch from 2efe9fd to 6341cc9 Compare November 18, 2026 23:39
@d-molinari

Copy link
Copy Markdown
Contributor Author

/ok to test 6341cc9

@svcnvidia-nemo-ci svcnvidia-nemo-ci added the risk:high Autobot PR risk: high label Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:core Shared APIs, servers, telemetry, health, and registries feature New capabilities, enhancements, or enablement work needs-review PR is ready for code review and waiting on a reviewer risk:high Autobot PR risk: high sla:review-overdue Review response is over the one-business-day SLA

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants