[Kh4L]

What does this PR do?

This PR moves the Stirrup sandbox and runtime work from gdpval-devel to main. On devel it landed as #2338, #2395, #2588, #3086, #3121 and #3333 (sandbox part). It is one of a series of PRs cut by file from a single tested devel snapshot. It touches responses_api_agents/stirrup_agent/ and the GDPVal sandbox build script in nemotron_recipes/. The GDPVal prompt rewrite that describes this sandbox is in #3686, not here.

Sandbox (#3333)

• containers/gdpval.def now builds the published GDPval-AA v2 environment:
  • debian:trixie with Debian's Python 3.13.5. The build fails on any other interpreter version.
  • The 419 published Python pins, installed verbatim and checked for exact versions afterwards.
  • Carlito/Caladea (metric-compatible Calibri/Cambria) and the Noto fonts.
• Both published manifests are vendored as plain text: 419 Python pins and the 762-package apt closure. On arm64 the build drops exactly the 5 pins in gdpval_aa_v2_arm64_exclusions.txt. Any other pin that fails to install fails the build.
• verify_gdpval_sandbox.py is staged into the image. It checks a built .sif against both manifests, then runs the toolchain end to end.
• The definition stages its manifests with relative %files paths, so it has to be built from containers/. The README command is updated for that. nemotron_recipes/.../build-gdpval-sif.sh now builds from the definition's directory, where before it built from the repo root, which fails with this definition.
• _build_command_script is pulled out of ApptainerCodeExecToolProvider._exec with no behaviour change. A test runs two provider-built commands in one bash and checks that only files persist between calls.

Model client and agent (#2338, #3121)

• DynamicMaxTokensChatCompletionsClient:
  • When the tokenizer renders the complete prompt, the remaining context also caps max_completion_tokens. A prompt with no room left raises Stirrup's ContextOverflowError before the request is sent.
  • For token counting only, tool-call arguments are JSON-decoded before template rendering, as vLLM does.
  • Without a tokenizer, or when tokenization fails, the character estimate counts the whole JSON-serialized history, tool calls included.
  • New arguments:
    • min_completion_tokens, default 1024 (the old constant).
    • prompt_estimator_truncate_history_thinking, default None. It only affects the estimate.
    • truncation_recovery, default False. When on, a turn that uses its whole budget without a schema-valid tool call is followed by one turn that requests thinking off and adds a one-time instruction. The instruction is not recorded in the trajectory.
• NeMoAgent.summarize_messages:
  • Strips a leading <think> block from compaction summaries.
  • Makes up to 3 summary attempts. Retries add a stricter text-only instruction, and the last attempt runs without tools. If all 3 fail it raises instead of wiping the history.
  • New min_compaction_summary_words argument, default 1.

Provider payload and trajectories (#2395, #2588, #3086)

• to_provider_openai_messages sends only the standard OpenAI message keys:
  • Stirrup's serializer also emits reasoning_content, thinking_blocks and metadata on assistant messages, flat tool_call_id/name/arguments/signature fields on tool calls, and name on tool messages.
  • Main's strict chat schema rejects those fields. So any multi-turn request whose history has an assistant turn with tool calls or reasoning currently fails against a Gym model server.
  • Unparsed <tool_call> / <function=...> blocks are removed from the provider copy of assistant text. This applies only to assistant turns with no parsed tool_calls, and an unclosed block is stripped to the end of the message. The recorded history keeps them.
• convert_stirrup_history_to_output_items makes call_id unique within a response when the server reuses ids across turns (e.g. code_exec:0). Call/output pairing is preserved, and trajectories without repeated ids are unchanged.
• Tavily web_fetch:
  • If markdown extraction is empty, it tries a second plain-text pass that includes comments. If that is also empty it returns an explicit error.
  • An extraction under 1% of a page of 20,000+ characters gets a "likely a fragment" note at the start.

The new client and agent options are documented in the Stirrup README as constructor arguments. The agent config keys that set them come with #3686, which owns stirrup_agent/app.py.

Issue: none. This promotes work that was already reviewed and merged on gdpval-devel.

Dependencies:

• CI: none. This PR passes the Stirrup and GDPVal suites on main by itself.
• Runtime, already true on main before this PR: main's strict chat schema returns 422 for the chat_template_kwargs that Stirrup's client sends on every call. Running Stirrup against a Gym vLLM model server therefore needs fix(openai-utils): accept provider extension fields in strict chat requests #3682.
• Thinking control: under fix(openai-utils): accept provider extension fields in strict chat requests #3682's current default (forward_request_chat_template_kwargs: false), the model server accepts request chat_template_kwargs and drops them. That means Stirrup's enable_thinking, and the thinking-off half of truncation_recovery, reach vLLM only when the policy model server sets forward_request_chat_template_kwargs: true. The GDPVal config in feat(gdpval): harden judging with local judges and media inputs #3686 doesn't set it, so there only the recovery instruction takes effect. The default is still open on fix(openai-utils): accept provider extension fields in strict chat requests #3682.
• feat(gdpval): harden judging with local judges and media inputs #3686 (lands after this one):
  • It brings the GDPVal prompt rewrite (code_exec, no shell state between calls, the 5-minute limit, the AA v2 package summary). It also brings the reference-file path fix that prompt relies on, and the tests that tie the prompt to this sandbox's manifests.
  • It adds the agent config keys context_window_tokens, min_completion_tokens, prompt_estimator_truncate_history_thinking, min_compaction_summary_words and truncation_recovery.
  • Until it lands, main's prompt keeps advertising run_shell and packages the image doesn't have (torch, keras, jax, dlib). Main's current image doesn't have them either. The new options keep their defaults, and the context window still comes from the request's max_output_tokens (fallback 262144).

Validation

Main 1c8261080 + only this PR's 17 files, macOS, Python 3.13, per-server venvs:

• cd responses_api_agents/stirrup_agent && python -m pytest tests -q: 224 passed, 2 skipped. The skips need GNU timeout or a real Apptainer image (GDPVAL_CONTAINER_PATH).

• cd resources_servers/gdpval && python -m pytest tests -q (gdpval imports Stirrup): 156 passed.

• With the rest of the series applied: Stirrup 319 passed / 2 skipped, GDPVal 564 passed. The 12 prompt-content tests that moved to feat(gdpval): harden judging with local judges and media inputs #3686 fail against main's current prompt, which is why they live there.

• pre-commit run --all-files: all hooks pass, no files modified.

• Schema probe against main's NeMoGymChatCompletionCreateParamsNonStreaming:

  History	Stirrup's to_openai_messages	to_provider_openai_messages
  Assistant tool call + tool result	rejected (44 errors)	validates
  Assistant reasoning, no tool calls	rejected (14 errors)	validates
  Text only	validates	validates

  Adding chat_template_kwargs is still rejected until fix(openai-utils): accept provider extension fields in strict chat requests #3682.

• Build script: I ran it with a stub apptainer that checks every %files source resolves from the build directory.

  • The new script passes for the default, a relative and an absolute output path.
  • Main's script fails: gdpval_aa_v2_python_requirements.txt is not found from the repo root.

• Container: built and verified with verify_gdpval_sandbox.py in [GDPVal] Align the sandbox and prompt to GDPval-AA v2 #3333. The image was not rebuilt for this PR, and only comment lines under containers/ have changed since.

  Arch	Interpreter	Pins	apt-closure entries missing	Verifier failures
  x86_64	3.13.5	419/419	0	0
  aarch64	3.13.5	414/419 (the 5 listed exclusions)	3	0

• Core unit tests: not run. This PR changes nothing under nemo_gym/, scripts/ or tests/.

Rollouts

Live GDPVal smoke (final code): all seven PRs of the series applied together on main 1c8261080, run with the devel-only SLURM launcher on a 4-task AA-v2 comparison smoke (one 4-GPU policy node, CPU judging): rollout 4/4 tasks saved and finished (1h04m, 0 failure rows), Office preparation 7/7 converted, comparison judging 4/4 tasks judged with 0 imputed and 0 excluded, 3 wins / 1 loss. Per-task outcomes match an earlier gdpval-devel run on the same checkpoint, tasks and references. No rate limiting occurred, so the judge retry budget was not exercised live.

Compatibility and benchmark impact

• Sandbox image (takes effect only after a rebuild):
  • Existing .sif images keep working.
  • Build from containers/ (cd responses_api_agents/stirrup_agent/containers && apptainer build gdpval.sif gdpval.def) or with the recipes script. A build started from the repo root cannot find the %files inputs.
  • Python packages:
    • The base moves from python:3.13-bookworm to debian:trixie, with Python fixed at 3.13.5.
    • Python packages become exact pins. Every Python package the old definition installed is still in the pin set.
  • apt: unar is dropped (it isn't in the AA v2 closure), and three packages move to their trixie names.
  • Deliberate differences from AA v2: we keep a compiler toolchain, we add espeak-ng, and the per-command limit is 5 minutes (AA uses 10).
• GDPVal results: runs on a rebuilt image are not comparable with runs on an image built from the old definition. Package versions, fonts and LibreOffice all change. The prompt change in feat(gdpval): harden judging with local judges and media inputs #3686 moves scores further.
• Token budgeting (all Stirrup runs):
  • With model_id set and a template that renders, max_completion_tokens can drop below 1024 near the context limit, and a full context raises ContextOverflowError before the request is sent.
  • Without model_id, or when tokenization fails, the estimate is larger for every history, most for tool-heavy ones. Budgets shrink only near the context limit, and the 1024 floor still applies.
• Constructor validation: max_completion_tokens_cap, min_completion_tokens and min_compaction_summary_words below 1 now raise ValueError.
• Logging: a WARNING is logged every time a call uses its whole completion budget without a usable tool call, even when truncation_recovery is off.
• Compaction: empty or think-only summaries now get up to 3 attempts and then fail the rollout. Before, the run continued with an empty summary.
  • The override uses private Stirrup internals (_unwind_context_overflow, _active_tools, _logger). They are stable under the existing stirrup>=0.1.12,<0.2 pin, but a Stirrup minor release may need a follow-up.
• Provider requests:
  • The non-standard message keys listed above are no longer sent, so earlier-turn reasoning is not replayed.
  • Unparsed tool-call blocks are removed from the provider copy of assistant text.
• Trajectories: a repeated tool call_id gets a #n suffix from its second occurrence onward.
• web_fetch:
  • A page with no extractable text now returns success=False with an error. Before, it returned an empty body.
  • A fragmentary extraction gets a note at the start.
• Opt-in behaviour: truncation_recovery is off by default. When on, the recovery instruction is appended as a user message, so the provider can see two user messages in a row.
  • feat(gdpval): harden judging with local judges and media inputs #3686 turns it on for GDPVal and also sets min_completion_tokens: 8192 and min_compaction_summary_words: 50. Other Stirrup users are unaffected.
  • Until feat(gdpval): harden judging with local judges and media inputs #3686 lands, those keys in agent YAML have no effect: StirrupAgentWrapperConfig accepts extra keys and ignores them.

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.
• Pre-commit checks pass locally (pre-commit run --all-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).

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

[yuhezhang-ai]

/ok to test 18c6678

[github-actions]

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/36800414919