feat: Switchyard OpenCode integration

[drifold]

Stacked on #2026 (base: feature/switchyard-openhands-integration). Adds upstream opencode as a second harness for the Switchyard token-capture integration — same zero-fork principle as the OpenHands path — plus per-run Switchyard instance spawning for token injection.

What

• Runs opencode headless (opencode run) with an opencode.json provider pointed at Switchyard — no fork, no harness modification.
• Captures the session tree through opencode's own correlation headers: a distinct X-Session-Id per (sub)agent session, x-parent-session-id linking subagents to the root.
• Reconstructs the root session as the main rollout and subagent sessions as token-annotated subagent_trajectories.
• Per-run Switchyard instances: switchyard_spawn_routing_profile spawns one dedicated token-capture Switchyard instance per agent run on a free port — stateful token injection (feat: token-level capture for RL training (Switchyard ↔ NeMo Gym) Switchyard#63) requires all of a session's calls to reach one process — and reaps it after trace retrieval in run().

Zero-fork architecture

• The opencode.json provider id is deliberately not opencode-prefixed — opencode only emits its native correlation headers for non-opencode providers; those headers are the whole capture contract.
• Gym mints no session ids here: opencode's own ids om Switchyard's GET /v1/sessions (no harness logs
  read).
• Title-generator side-calls (same session id, different conversation) are filtered before reconstruction.

Activation and safety

swe_agents:
  responses_api_agents:
    swe_agents:
      agent_framework: opencode
      opencode_source: opencode        # now the default; use "nv-opencode" for the fork
      switchyard_base_url: http://<host>:<port>
      # OR spawn mode (mutually exclusive with switchyard_base_url)
      # switchyard_spawn_routing_profile: /abs/path/

condition	behavior
opencode_source: nv-opencode	fork path (bench entrypoint)
upstream (opencode_source: opencode, now default+ subagents reconstruct
retrieval/reconstruction failure	rollout kept, switchyard_trace_error set
switchyard_spawn_routing_profile absent	behavichyard_base_url` or no Switchyard)
spawn mode enabled	per-run instance, records under persistent_dir, instance reaped after retrieval

Changes

• responses_api_agents/swe_agents/app.py — opencovider JSON), the opencode run command, _list_switchyard_sessions/_reconstruct_sessionssk_id steering via system-prompt instructions (works
  around an opencode quirk where it invents task_ids).
• responses_api_agents/swe_agents/app.py — switchyard_spawn_routing_profile / switchyard_spawn_host config (mutually exclusive
  with switchyard_base_url, validated fail-fast), specycle, agent-script build deferred until theinstance URL is known.
• responses_api_agents/swe_agents/app.py — openco to opencode` (upstream); config comment/docs updated
  accordingly.
• responses_api_agents/swe_agents/configs/ — splitnch_opencode.yaml/swebench_opencode_training.yaml now target **upstream** opencode (opencode_source: gs move to swebench_nv_opencode.yaml /
  swebench_nv_opencode_training.yaml (`opencode_soured). Root README table regenerated.
• nemo_gym/switchyard_trace.py — canonicalize toolstory-extension comparison only (opencodere-serializes compact vs. pretty-printed JSON across turns); reconstructed items keep the model's original arguments.
• Tests: 8 new test classes across test_app.py and`, plus 7 spawn-lifecycle tests (config conflicts,session minting + script rebuild, spawn/teardown with mocked subprocess, readiness-failure reaping).

Dependencies

Requires the Switchyard side on NVIDIA-NeMo/Switchya

• 7b33c2c (native X-Session-Id capture), be0b2c5r the opencode capture path.
• 7f20b2a, 940b767, 8307fd9 (token-continuity ion use-case; spawn mode itself works withcapture-only).

Testing

• 232 passed across the swe_agents and `switchyard
• Cluster E2E (vLLM 0.24.0, Qwen3): root + subagent ode headers, both reconstruct with exact token
  fidelity, 0% masked; with token injection enabled, buous across multi-turn reasoning + tool-calling
  conversations (0 fallbacks), and an OpenHands-pattertiguity verification.

Changes from the live description are only: the openthe first two behavior-table rows (fork now keyed onnv-opencode; upstream noted as default), and two addault flip + config split). Everything else — including the - bullets, headings, dependency SHAs, and the vLs unchanged.

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