fix(core): serve the environment's own State subclass on /schema and /state

[k21993]

Summary

/schema and /state were wired to the base State model, so every field an environment declared on its own State subclass was missing from the published schema and stripped from the response body. The WebSocket state frame calls model_dump() on the live session environment and keeps those fields, so the two transports disagreed about the same object. This threads an optional state_cls through the app factories and uses it for the /state response model and the state entry of /schema.

Fixes #1155.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run lint and tests and addressed all issues

On the last box: uv is not on my shell PATH, so I ran the checks in a Python 3.11 virtualenv with the test dependencies rather than through .claude/hooks/lint.sh. Details in the test plan.

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: #___
• RFC needed (will create before merge)

The parameter is additive and defaults to State, so behaviour is unchanged for every existing caller, and it adds no new abstraction or change to the two-interface model. The pre-submit checklist treats a public signature change in src/openenv/core/ as RFC territory while the RFC guidance exempts bug fixes, so I have left these unchecked rather than decide it myself. #1155 proposes exactly this parameter and default. Happy to write a short RFC before merge if you would prefer one.

Test Plan

New file tests/core/test_state_schema_subclass.py, eight cases across two groups: an environment that declares EchoState gets counter and history in both /schema and /state, including through create_app with the web interface enabled or disabled. Action and observation schemas are unaffected, and an app that declares nothing keeps the exact base-model behaviour it has today.

Before adding the two create_app mode cases, reverting the source files and rerunning the original six tests gave 3 errors, 1 failure and 2 passes. The errors are the fixtures rejecting the unknown state_cls argument, the failure is the missing state_cls attribute, and the 2 that still pass are the default-path tests, which is the intended result: they exist to catch a regression in the untouched path, so they should pass both before and after.

• tests/core: 621 passed, 1 skipped.
• Standard CI test selection before the final two factory-mode cases: 1,955 passed, 92 skipped and 37 deselected in the sandbox. The two socket-binding tests blocked by the sandbox both passed when rerun with local socket access. The final two factory-mode cases and the full core suite were then rerun successfully.
• usort check, ruff format --check, ruff check on the three changed files: clean.
• The repository-wide lint hook reports existing formatting differences on 57 files and existing usort differences in test_grid_world.py and test_julia_env.py; no changed file is among them.
• Environment: Python 3.11 isolated virtualenv with pytest, fastapi, fastmcp, gradio, openai, websockets and the other test dependencies, run as PYTHONPATH=src:envs python -m pytest.

Two notes for review:

state_cls is the last parameter on create_app and create_web_interface_app rather than sitting next to action_cls and observation_cls, so no existing positional argument shifts. I checked every create_app, create_fastapi_app and create_web_interface_app call in src/ and envs/ with an AST scan: none passes more than three positional arguments today, but the ordering keeps out-of-tree callers safe too.

Deriving the class from Environment[ActT, ObsT, StateT] would avoid the parameter entirely, but only five environment packages currently parameterize that generic (maze_env, tbench2_env, pelican_svg_env, thinkingbox_env, and sophistry_bench_sprint_env); the last uses the base State. Some other environments annotate the state property as returning the base State, so generic inference would miss most of the affected environments.

The 28 environments that declare a State subclass each need a one-line change to pass it. I left that out to keep this diff to the core fix, and I am happy to add it here or in a follow-up, whichever you prefer.

Claude Code Review

Checked against PRINCIPLES.md and INVARIANTS.md: no Tier 1 issues in this diff, no principle conflicts, and no RFC conflicts. The change stays inside the HTTP transport surface and does not touch the agent and orchestration boundary or client and server separation.

---

Note

Low Risk
Additive API defaulting to base State; behavior unchanged for existing callers until environments pass state_cls.

Overview
Fixes a transport mismatch where HTTP /schema and /state always used the base State model, so subclass fields were dropped from the published schema and JSON body even though WebSocket state frames kept them.

Adds an optional state_cls parameter (default State) on HTTPEnvServer, create_app, create_fastapi_app, and create_web_interface_app, and wires it into the /state OpenAPI response model and the state section of /schema. Callers that pass their environment’s State subclass get those fields published and serialized; omitting state_cls preserves prior behavior.

New regression tests in tests/core/test_state_schema_subclass.py cover declared vs default state_cls, including create_app with the web interface on or off.

^{Reviewed by Cursor Bugbot for commit 0cef418. Bugbot is set up for automated code reviews on this repo. Configure here.}

[k21993]

@burtenshaw the workflows here are sitting at action_required, so Tests, Package CI and the docs build have not run yet. Could you approve the runs when you get a chance?

Maintainer edits are enabled on this branch, it is current with main at 08af2d2f, and Bugbot is green on the current head.

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[burtenshaw]

thanks!

[cursor]

Release-manager triage at head 66ccdb83. The bug is real and I confirmed it on main: http_server.py:1421 declares response_model=State and http_server.py:1480 publishes State.model_json_schema(), so any field an environment adds on its own State subclass is both absent from /schema and stripped out of the /state body — while the WebSocket state frame calls model_dump() on the live environment and keeps those fields. Two transports disagreeing about the same object is worth fixing, the approach (thread an optional state_cls, default State) matches what #1155 proposed, and putting the parameter last so no existing positional argument shifts is the right call.

I am not merging this, and the reason is not the code. It adds a parameter to create_app and create_web_interface_app, which are public core factories, so it needs a maintainer decision rather than a release-manager merge. Your own instinct in the description is the right one: additive-with-a-default is normally not RFC territory, but the signature is public surface and that call is not mine to make. Two questions for whoever takes it:

1. Is state_cls the interface you want long-term, or should Environment[ActT, ObsT, StateT] become the single source of truth? You note only five env packages parameterize that generic today, which is a fair argument for the explicit parameter now — but it is worth deciding whether the parameter is the destination or a bridge, because removing it later is a breaking change.
2. The 28 environments that declare a State subclass each still need a one-line change to actually benefit. Shipping the core fix without them means /schema stays wrong for all of them, so the follow-up should be tracked rather than implied.

The practical gate: repository CI has never run here — only Bugbot has, and the branch is behind main. It needs a maintainer to approve the workflow run, and a refresh onto current main (4a1fa2a8). Not in the 0.5.0 candidate (#1190) and not holding the release.

View PR

  

_{Sent by Cursor Automation: Release}