Repository navigation
Add reset schema publication to /schema endpoint - #1270
Conversation
Environments can now declare their custom reset() parameters as a ResetRequest subclass and pass it as `reset_cls`. GET /schema publishes that model's JSON schema under a new `reset` key, alongside action, observation and state (proposal openenv#1215). It mirrors the state_cls plumbing from openenv#1174. - SchemaResponse gains `reset: Optional[Dict[str, Any]]` (default None, so it can still describe responses from older servers). - `reset_cls: Type[ResetRequest] = ResetRequest` is added as the last keyword parameter of HTTPEnvServer.__init__, create_app, create_fastapi_app and create_web_interface_app, threaded exactly as state_cls is, and stored as HTTPEnvServer.reset_cls. Without it, /schema publishes the base ResetRequest schema. - The /schema route description, OpenAPI example, the "Schema" tag and the app's feature list mention reset parameters. - Hint only: /reset and the WebSocket reset message still parse with ResetRequest and filter keys against reset()'s signature. reset_cls never produces a 422 or an error frame. - openenv validate is unchanged; it does not require the new key, so servers on older openenv releases still pass. - Task API guide: short example of a ResetRequest subclass passed as reset_cls. CLI env template docstring lists state/reset schemas. - tests/core/test_reset_schema.py covers publication with and without the web interface, inherited seed/episode_id fields, unaffected action/observation/state schemas, the base-schema fallback, and that /reset bodies are not validated against reset_cls. No deviations from the spec. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vd6SA9aV1SAmUBCewkcVsZ
|
will resolve conflicts if maintainers want this PR, but some 👍 👎 would be good. |
|
@burtenshaw is this something you'd want to to take? I can resolve conflicts but not sure if you want it or not. |
|
Resolved main conflicts, preserving mode and reset-observation wiring. Added WebSocket non-validation regression and RFC 002 amendment for the new core parameter. 888 core tests pass; changed-file lint passes. Required CI is outstanding. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit c3a4d35. Configure here.
Summary
There's no way for a client to see the
reset()schema, while action/observation/state all expose their scheme via/schema. By also exposing reset schema following existing conventions, clients can build much nicer UIs (see example screenshot below), and agents know what to send.Fixes: #1215
This PR adds a
reset_clsparameter to the HTTP server and app factories, so an environment can declare its reset parameters as aResetRequestsubclass./schemapublishes that schema under a newresetkey, following the existingstate_cls/action_cls/observation_clspattern. The schema is a hint only: reset requests are not validated against it.Type of Change
Alignment Checklist
.claude/docs/PRINCIPLES.mdand this PR aligns with our principles.claude/docs/INVARIANTS.mdand no invariants are violated/pre-submit-pr(orbash .claude/hooks/lint.shand tests) and addressed all issuesRFC Status
reset()schema to/schema#1215.Changes
types.py:SchemaResponse.reset: Optional[Dict[str, Any]] = None.http_server.py:reset_cls: Type[ResetRequest] = ResetRequestas the last kwarg onHTTPEnvServer.__init__,create_app,create_fastapi_app, threaded likestate_clsand stored asHTTPEnvServer.reset_cls./schemareturnsreset=self.reset_cls.model_json_schema(); route description, OpenAPI example and tag text updated.web_interface.py:create_web_interface_apptakes and forwardsreset_cls./resetbody model, WebSocket reset, signature filtering,openenv validate.docs/source/guides/task-api.md; CLI template docstring line.Test Plan
tests/core/test_reset_schema.py(new):reset_clsfields published on/schema, withENABLE_WEB_INTERFACEon and offseed/episode_idpresent; action/observation/state schemas unaffectedPOST /resetwith a wrong-typed declared field plus an undeclared key returns 200 and both reachreset()(no validation)reset_clspublishes the baseResetRequestschemaExample
Here's an example UI build using reset schema:
Note
Low Risk
Additive API and schema metadata only; reset request handling and validation are unchanged, with tests covering backward-compatible SchemaResponse serialization.
Overview
Environments can now advertise reset parameters on
GET /schemathe same way action, observation, and state schemas work today. App factories andHTTPEnvServertake an optional keyword-onlyreset_cls(ResetRequestsubclass, defaultResetRequest);/schemaadds aresetJSON Schema from that class.SchemaResponsegains an optionalresetfield that is omitted from serialized output when unset, so older three-field payloads stay valid.This is discovery only: HTTP
/resetand WebSocketresetstill use the baseResetRequestbody and existingreset()signature filtering—nothing is validated againstreset_cls. Docs (task-api.md, RFC 002 amendment) describe declaring subclasses (e.g.split/indexfor task selection); new tests lock in publication, defaults, and non-validation behavior.Reviewed by Cursor Bugbot for commit 45c756c. Bugbot is set up for automated code reviews on this repo. Configure here.