feat(workflow): add OpenEnvWorkflow adapter for HuggingFace OpenEnv

[NancyFyong]

Description

Add a generic OpenEnvWorkflow that speaks the
HuggingFace OpenEnv protocol so any
OpenEnv-compatible environment (BrowserGym, OpenSpiel, coding sandboxes,
chess, echo, ...) can be trained against with GRPO through YAML alone -- no
new Python per environment.

Key pieces:

• areal/api/openenv_api.py — OpenEnvConfig dataclass + ActionParser / ObservationFormatter Protocols, with post-init validation (base_url xor provider, provider extras).
• areal/workflow/openenv.py — OpenEnvWorkflow.arun_episode drives the reset() → [chat.completion → parse action → env.step()] * N loop. Per-step rewards go on each LLM completion via ArealOpenAI.set_reward, so GRPO grouping sees per-turn advantages. Supports terminal_reward_only, backward step_discount propagation, and an optional reward_shaping_fn.
• areal/workflow/openenv_utils.py — default JSONActionParser / TagActionParser / PassthroughActionParser; AutoObservationFormatter that JSON-encodes dataclasses / dicts / objects. Users can drop in custom parsers via dotted import path.
• Non-Docker path: the workflow lazily imports UVProvider when provider="uv", so the whole thing works on Slurm / K8s clusters without a Docker daemon.
• examples/openenv/ — shared train.py + echo_smoke.yaml (public HF Space, zero local install) + blackjack_grpo.yaml (UVProvider path).
• docs/en/customization/openenv.md — 5-minute guide covering install, parsers, formatters, reward propagation, and wiring in a new env.
• tests/test_openenv_workflow.py — 22 unit tests with mocked EnvClient / ArealOpenAI.

Related Issue

Addresses the "Support OpenEnv in Agentic RL" H2 2026 roadmap item in #1381.

Type of Change

• ✨ New feature

Checklist

• Pre-commit hooks pass (ruff check / ruff format --check on all new files)
• Relevant tests pass; new tests added for new functionality
  • pytest tests/test_openenv_workflow.py → 22/22 pass in ~35s
• Documentation updated (docs/en/customization/openenv.md + toc entry + example README)
• Branch is up to date with main
• Self-reviewed via /review-pr command
• This PR was created by a coding agent via /create-pr
• This PR is a breaking change

Additional Context

Verification performed:

Layer	Test	Result
1	pytest tests/test_openenv_workflow.py (22 tests: config validation, parsers, formatter, arun_episode reset/step loop, done early-exit, max_turns cap, terminal_reward_only, step_discount hook)	✅ 22/22 in 35s
1a	ruff check + ruff format --check on all new files	✅ clean
2	End-to-end against the public echo HF Space (https://openenv-echo-env.hf.space) — real WebSocket, real observation payload	✅ episode completes, rewards recorded
3	5 episodes × random policy against the public OpenSpiel HF Space	✅ each episode 9 turns → done, rewards ∈ {−1, +1}

Not yet verified locally:

• Full multi-step GRPO training on a real GPU with SGLang inference (skipped due to shared-machine constraints). Trainer plumbing goes through the identical RolloutWorkflow + ArealOpenAI path that MultiTurnV2Workflow uses.

Design notes:

• The workflow deliberately depends on openenv>=0.4 (async EnvClient API landed in 0.4; 0.2.x is sync-only). Pinned as an optional extra.
• Actions round-trip as either a dict, a dataclass instance (via action_class), or a raw string; the parser layer decides. GenericEnvClient accepts plain dicts and covers ~all built-in envs by URL alone.
• No cluster / launcher changes. New workflow is loaded lazily via areal.workflow.__init__, so users who never touch it don't pay any import cost.

How to try it locally:

uv sync --extra cuda --extra openenv --group dev
# Smoke: zero-GPU workflow test against the real echo Space
uv run pytest tests/test_openenv_workflow.py -v
# Full training entry point
uv run python examples/openenv/train.py --config examples/openenv/echo_smoke.yaml

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity within the last 14 days.

Please add a comment or push new commits to keep it active.

Thank you for your contribution!