The OpenEnv protocol, as this implementation understands it
This page is our statement of the OpenEnv protocol: what a conforming server puts on a wire, written from captured traffic rather than from anybody's documentation. It is short because the protocol is short. Everything long about OpenEnv is a Python library that speaks it.
It is normative for this repository and nothing else. Where it differs from
the reference — huggingface/OpenEnv, the Python implementation this repository
was captured from — the reference wins. WARTS.md records each
such difference at the line that reproduces it. Where nothing decides,
GAPS.md says so. A WART-nn, GAP-nn or CONF-nn below is a
numbered entry in those ledgers: a reference accident we reproduce, a question
the protocol does not answer, or a conformance requirement. How all of it was
derived is PROVENANCE.md.
There is no protocol version anywhere in OpenEnv. Not in a header, not in a payload, not in the handshake.
GET /openapi.json'sinfo.versionis the closest thing that exists, and it describes the document, not the wire. This is worth knowing before you read the rest: nothing below can be negotiated.
1. The shape, in one paragraph
A conforming server is an HTTP/1.1 server on TCP port 8000, bound 0.0.0.0,
that answers GET /health and accepts a WebSocket upgrade at /ws. Over that
socket it speaks text frames, one JSON object each, strictly lock-step: one
client message, exactly one server response. No pipelining, no correlation
ids, no server-initiated frames. An episode — one run of the loop: a reset,
then steps, until done — happens on that socket and nowhere else.
Everything else the server exposes — the fourteen other routes, the schema,
the /mcp tool surface — is discoverable and optional in practice.
2. The sixteen routes
The table in ../src/proto/routes.c ↗ is the executable
form of this, and tests/t_routes.c asserts the count.
| Method | Path | Answers | In /openapi.json? |
|---|---|---|---|
GET, HEAD | /openapi.json | the document. info.version selects the conformance profile | no — it cannot describe itself |
GET | /list_environments | ["<task name>"]. One row: a server is one environment | yes |
GET | /{env_name}/splits | Task API | yes |
POST | /{env_name}/tasks | Task API | yes |
POST | /{env_name}/num_tasks | Task API | yes |
POST | /{env_name}/task | Task API | yes |
POST | /{env_name}/task_range | Task API | yes |
| — | WS /mcp | bare JSON-RPC, spaced separators | no — OpenAPI cannot describe a WebSocket |
POST | /reset | the four-key envelope. Stateless | yes (simulation mode only) |
POST | /step | the four-key envelope. Stateless | yes (simulation mode only) |
GET | /state | episode_id and step_count, and nothing else | yes (simulation mode only) |
GET | /metadata | six keys, fixed order | yes |
GET | /health | {"status":"healthy"} | yes |
GET | /schema | action, observation, state | yes |
POST | /mcp | JSON-RPC 2.0, four methods, always HTTP 200 | yes |
| — | WS /ws | the episode | no |
Registration order is observable. The five templated Task API rows are
registered before the fixed one-segment paths. That is why GET /nope/splits
reaches a handler that knows the word "environment" and answers
{"detail":"unknown environment 'nope'"}, while GET /nope falls through to
{"detail":"Not Found"}. Two different 404 bodies on one server; WART-15.
Three rows are simulation-only. Production mode removes /reset, /step
and /state and answers 404 for them. Never 405: the row ceases to exist,
and the 404 is decided before the method is looked at. WS /ws is left
untouched, so the stateful transport survives and the stateless mirror does
not. This project serves both modes: oe_serve_opts.production (and the
production parameter of oe_http_handle) selects the reference's
ServerMode.PRODUCTION, with simulation the default. Nothing in the reference
tree reaches production from a shipped entry point. So the corpus — the
captured reference traffic in tests/fixtures/reference-corpus.json — records
it against a purpose-built server on port 8903 (cases 43-45), and those cases
replay byte for byte with the flag set.
The four defaults that come from the framework, not the application
They are on the wire, so they are part of what a compatible server produces
(CONF-22):
| Request | Answer |
|---|---|
a trailing slash on a real path (GET /health/) | 307 with location |
a real path, wrong method (GET /reset) | 405 with allow: POST |
HEAD or OPTIONS on any core route | 405 — they are ordinary wrong methods, not separate mechanisms (WART-21) |
| any unmatched path | 404 {"detail":"Not Found"} |
The Task API — six routes, five of them provider-backed
Six of the sixteen routes are a discovery surface for dataset-backed
environments. They are the one part of the protocol this implementation
documents but declines to implement (GAP-24). Every environment this
project ships answers the five provider-backed routes with 501. That is a
conforming answer — the route is registered, the provider is absent (CONF-20,
requirement 8.A.20) — and GET /list_environments needs no provider at all.
The shapes below are what a reference environment WITH a provider does return.
All were captured byte for byte from the live reference (interop/task_env.py):
| Route | Success shape | Corpus |
|---|---|---|
GET /list_environments | ["<task name>"] — one row; a server is one environment | 5, 96 |
GET /{env}/splits | [{"name":…,"type":…}, …] — a bare array of split objects | 97 |
POST /{env}/tasks | {"tasks":[…],"env_name":"<name>"} — the only route that echoes env_name | 98 |
POST /{env}/num_tasks | {"num_tasks":<int>} | 99 |
POST /{env}/task | {"task":{…}} | 100 |
POST /{env}/task_range | {"tasks":[…]} — Python slice bounds, and no env_name | 101 |
The four POST bodies are {"split":<str>} (tasks, num_tasks), plus
"index":<int> (task) or optional "start"/"stop" (task_range). A missing
split is a 422 the framework raises before the handler runs (case 30).
_normalize_split types an unknown split "validation". list_splits may
return bare strings; the SERVER wraps each as {"name","type"}. A name that
is not one of train/validation/test is silently given type:"validation"
(READ from http_server.py:1070-1080). So an environment whose splits are
train, test and holdout publishes the last as
{"name":"holdout","type":"validation"} — corpus case 97, the wart as bytes.
Two 404s, a 501, and an undocumented 400 — decided by order. env_name is
matched case-insensitively against the REGISTERED name, not the class name
GET /metadata reports (WART-15). A mismatch is the second 404:
{"detail":"unknown environment '<name>'"}, cases 26-28. A match on a
provider-less environment is a 501 naming the Python method:
{"detail":"list_splits is not supported for this environment"}, cases 91-95.
An out-of-range index on a provider env is an undocumented 400,
{"detail":"Invalid task index"} (case 102, READ from http_server.py:1094-1098).
That is a new row in ERRORS.md, and the only Task API status the
reference's own OpenAPI document never mentions.
Provenance: captured, and the divergence is REFUSED not out-of-scope. Every
shape above is in the corpus, from the live reference. The provider-less 501s
and list_environments were captured against counter_env on 8901; the real
dataset rows and the 400 against interop/task_env.py on 8907. Where this
implementation and a provider env part — the five success shapes and the 400 —
t_replay buckets it REFUSED (cases 97-102; the replay verdicts are defined in
CONFORMANCE.md). The bytes are OpenEnv's own and we could
emit them. But no upstream client consumes these routes, so we decline until
one does. That re-open condition is named, and it lives in the GAP ledger at
GAP-24.
3. The episode — WS /ws
Five client message types, four server response types. type first, data
second, compact JSON, no spaces.
// client -> server // server -> client
{"type":"reset","data":{}} {"type":"observation","data":{…}}
{"type":"step","data":{<action fields>}} {"type":"state","data":{…}}
{"type":"state"} {"type":"error","data":{…}}
{"type":"close"} {"type":"mcp","data":{…}}
{"type":"mcp","data":{<jsonrpc>}}
Three rules a plausible client gets wrong, each with a case in
tests/t_client.c named after it:
- The action is BARE.
datais the action object. The{"action":{…}}wrapping is HTTP-only.WART-16. stateandclosedeclare nodata. Sending one isVALIDATION_ERRORextra_forbidden— and a rejectedclosedoes not close.{"type":"close"}gets no reply frame at all, then a Close with code 1000 and an empty reason.WART-11,CONF-18.
The envelope
Every observation is these four keys, in this order:
{"observation": {…}, "reward": 3, "done": false, "metadata": {…}}
rewardisnull | true | false | <integer> | <float>. Adouble-only client field loses two of the five. On the WebSocket the value passes through untouched; on HTTP it is coerced to a JSON number (true→1.0).WART-03.- There is exactly one
done. No Gymnasiumterminated/truncatedpair, noinfo, no episode object. metadataappears twice — nested insideobservationand hoisted to the top level — and the hoisted copy is emitted only when it has a member.WART-02,WART-04.rewardanddoneare moved out ofobservation, not copied.data.observation.doneis not there at all: the nested dump is taken withexclude={"reward","done"}. A client that looks there reports whatever default its own lookup carried, never a value the server sent.GET /schemastill advertises both as observation properties, which is where that client learned to look. Two shipped upstream environments read it from there.
There is no episode state machine
step before reset is legal. step after done: true is legal, repeatedly.
Two resets in a row are legal. Sequencing is a client-side convention with
nothing on the wire behind it. GAP-01, GAP-02.
The seven error strings
A closed set. A client branches on code, never on message.
code | Extra keys in data | Socket after |
|---|---|---|
INVALID_JSON | — | stays open |
UNKNOWN_TYPE | — | stays open |
VALIDATION_ERROR | errors — an array of pydantic items | stays open |
EXECUTION_ERROR | — | stays open |
CAPACITY_REACHED | active_sessions, max_sessions | closes |
FACTORY_ERROR | factory_name | closes |
SESSION_ERROR | — | closes |
Two of those have no client message to be a reply to. The reference accepts
the WebSocket upgrade and only then refuses, so CAPACITY_REACHED and
FACTORY_ERROR arrive as an unsolicited first frame. WART-10, CONF-17.
The message strings are fixed formats and are pinned verbatim in
../src/proto/errors.c ↗ — including
"Server at capacity: %d/%d sessions active. Cannot accept new connections."
and "Unknown message type: %s", whose substitution is the peer's own bytes.
4. Validation errors
A VALIDATION_ERROR's errors array, and a 422's detail array, hold pydantic
items:
{"type":"missing","loc":["body","action"],"msg":"Field required","input":{}}
Eighteen type slugs occur, with exact msg strings; the table is in
../src/proto/validate.c ↗.
Validation is lax, not strict. The string "42" is a valid integer, and
"x" yields the slug int_parsing. That slug is the report of a conversion
that was attempted, so a strict validator cannot produce it at all. This is
not an optional nicety: see PROVENANCE.md.
Whether an item carries url is decided by the CODE PATH, not by the shape of
loc. This is the single most common thing to get wrong, and getting it from
loc produces plausible, wrong bytes:
| Origin | loc | url |
|---|---|---|
HTTP request-body validation — missing action, no body, malformed JSON, wrong Content-Type, seed:-1 | prefixed "body" | absent |
| everything else: HTTP action validation, all WebSocket validation | not prefixed | present |
FastAPI's request-body path is the only place in the stack that strips the
URL. It is also the place that adds the "body" prefix. That is why the two
travel together, and why exactly one call site in this implementation passes
the first value. WART-22, CONF-11.
5. The stateless HTTP mirror
POST /reset, POST /step and GET /state cannot hold an episode. Each
one constructs an environment, runs one call, and destroys it in a finally.
Two identical POST /step calls return the same observation. WART-01.
$ build/rel/bin/counter --port 8931 &
$ curl -s -H 'content-type: application/json' -d '{"action":{"amount":2}}' localhost:8931/step
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}
$ curl -s -H 'content-type: application/json' -d '{"action":{"amount":2}}' localhost:8931/step
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}
The same two steps over /ws, against the same binary:
$ ./build/rel/bin/oe_probe http://127.0.0.1:8934 --episode --steps 2 --action '{"amount":2}'
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":2},"total":4,"last_note":""},"reward":4.0,"done":true,"metadata":{"steps":2}}}
<< {"type":"state","data":{"episode_id":"ep-fixed","step_count":2,"total":4}}
2, then 4. That is the ten-second proof that HTTP cannot hold an episode, and
it is why the file that serves those three routes is called http_stateless.c.
Note the last line too: total is there over the WebSocket and is not in
GET /state's answer. That is WART-05 on one screen.
Three more things this mirror does that the WebSocket does not:
POST /resetvalidatesseed >= 0;WS resetvalidates nothing at all. Same operation, two strictnesses.WART-08.- The action is wrapped under
"action".WART-16. GET /statetruncates to the baseState—episode_idandstep_count, and every field your subclass declared is dropped. The WebSocket'sstatemessage returns the full dump.WART-05.
The last one matters to users rather than implementers. It is the honest
answer to can a non-Python client drive an arbitrary environment? — yes
for actions and observations, no for state. GET /schema's state member
is likewise hardcoded to the base model (WART-06).
Content-Type is load-bearing
Absent or non-JSON with a body → 422 model_attributes_type. No body at
all → 200. The header decides whether a body was sent. WART-18.
An unhandled environment error is not JSON
500 Internal Server Error, content-type: text/plain, body
Internal Server Error. A client that assumes every non-2xx is JSON breaks
here. WART-19.
6. /schema — how a non-Python client learns the shape
{"action": <schema>, "observation": <schema>, "state": <schema>}, each a JSON
Schema object. Two things about it are worth knowing before you generate one:
- It uses two key-ordering regimes in one document. Schema keywords are
ASCII-sorted; a model's properties are in declaration order.
WART-09. titleis derived from the field name:last_note→"Last Note". Andrequiredis omitted entirely when every field has a default.
The protocol owns three fields an environment author never declares: metadata
on every action, and done/reward/metadata on every observation. They are
injected by the framework and appear first.
7. /mcp — JSON-RPC 2.0, three framings
One dialect, three wires, and two of them differ only in whitespace:
| Where | Framing | Separators |
|---|---|---|
POST /mcp | bare JSON-RPC | compact |
WS /mcp | bare JSON-RPC | spaced — {"jsonrpc": "2.0", … |
{"type":"mcp"} on /ws | wrapped in the envelope | compact |
WART-13. Same server, two encodings, and nothing announces which you will get.
Four methods: tools/list, tools/call, openenv/session/create,
openenv/session/close. Anything else is -32601 "Method not found: <m>".
Every JSON-RPC error is HTTP 200. The status line describes the HTTP
exchange; the error member describes the RPC. POST /mcp with the body {}
must answer 200 with a JSON-RPC payload. That is one of the six criteria the
official validator checks (CONF-06).
Four behaviours a reasonable implementer gets wrong:
- a batch array is
-32700 Parse error, not-32600.WART-23. - a non-object
paramsis-32600 Invalid request, not-32602.WART-24. - a request that fails schema validation is answered with
"id":null, even when the request carried an id — the id is never extracted before validation.WART-25. - a notification (no
id) is answered anyway.WART-12.
The tool vocabulary, and the door rule
An environment either has a tool table or it does not, and both answers are
protocol. With none, tools/list and tools/call are
-32603 "Environment does not support MCP". That is the reference's own
answer, and the whole answer for three of the four environments this project
ships.
With one, a tool is three keys: a name, a description and an argument
schema. No title, no outputSchema, no annotations, no icons, no cursor, no
initialize, no session. And the schema's key is spelled differently on each
door, which is the one rule here that reads as arbitrary and is not:
| Door | Messages | Schema key |
|---|---|---|
trainer — POST /step, {"type":"step"} on /ws | {"type":"list_tools"} and {"type":"call_tool","tool_name":…,"arguments":{…}} as ordinary actions; the answer is an ordinary observation | input_schema |
agent — POST /mcp, WS /mcp, {"type":"mcp"} on /ws | tools/list and tools/call; the answer is a JSON-RPC result, and a call's result is the tool's bare return value | inputSchema |
Both spellings are the reference's own. The trainer door serialises
mcp_types.Tool, which is extra="forbid" over exactly
name/description/input_schema. The agent door's hand-written branch
(http_server.py:945-958) writes inputSchema. It matters because OpenEnv's
own LLM-facing converter reads inputSchema with no snake fallback
(llm_client.py:463). Fed the trainer door's payload, it tells the model the
tool takes no arguments. A client, unlike a server, must accept both —
that is requirement 8.B.18.
Two more facts a tool table does not change. A tools/call that carries no
name is -32602 "Missing 'name' in params" whether or not the
environment has tools, because the dispatcher answers about params first
(WART-27). And a name that is not in the table is
-32602 "Tool not found: <name>".
What we refuse here — one library's nine-key Tool dump, its CallToolResult
envelope, and the MCP specification's own lifecycle — is
NOT-THE-PROTOCOL.md,
with the bytes for each.
8. Bytes, exactly
| encoding | UTF-8, raw. No \uXXXX escaping on output |
| reading | a reader must decode \uXXXX including surrogate pairs |
| separators | compact everywhere except WS /mcp |
| numbers | reward is tagged: 0 and 7 have no .0; 7.0 and -1.5 do |
| floats | 2.0, not 2, on both transports — but the exponent is spelled differently by each. HTTP bodies are json.dumps of a dict, so CPython's repr: 1e-5 → 1e-05, 1e-6 → 1e-06. WebSocket frames are pydantic's model_dump_json, which stays in fixed notation a decade further: 1e-5 → 0.00001, 1e-6 → 1e-6. Nothing in the corpus pins this row — every captured reward is in the range where the two agree — so it rests on the two libraries' own rules, and tests/t_encoders.c asserts it. Row 4 of the divergence table in src/proto/encode.c |
| key order | insertion order, everywhere. GAP-03 records that nothing says it is contractual |
| duplicate keys | the last member wins for a lookup. GAP-16 |
The RFC 6455 handshake
Standard: base64(SHA1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")). The
server negotiates no subprotocol and sends no Sec-WebSocket-Protocol
(CONF-12). Client frames are masked, server frames are not. Text frames only —
a binary frame kills the session.
The container contract, in two sentences
Listen on port 8000, bound
0.0.0.0. AnswerGET /health.
CONF-01, CONF-02. Exit cleanly on SIGTERM within ten seconds (CONF-23);
docker stop's grace period is where that number comes from.
The twenty-three server requirements
These are the numbered requirements CONF-nn cites. Requirement n is cited
in the source at the line that satisfies it.
WARTS.md
is the generated index of where each one landed. Six of them — 1 through 6 —
are what openenv validate --url actually checks; the rest are observable and
unchecked by any official tool.
One requirement, two spellings, and both are in the source. CONF-nn marks
the LINE that satisfies requirement n. MUST 8.A.n is how a comment refers
to the requirement itself when it is arguing about what a peer may rely on.
They are the same number: 8.A is this table, 8.B is the next one.
tools/check.sh fails on a citation whose number has no row here.
| # | A minimal conforming OpenEnv server MUST |
|---|---|
| 8.A.1 | Listen for HTTP/1.1 on TCP port 8000, bound to 0.0.0.0 |
| 8.A.2 | GET /health → 200, content-type: application/json, body exactly {"status":"healthy"}, working before and independently of environment construction |
| 8.A.3 | GET /openapi.json → 200, info.version a string starting "1.", paths listing every HTTP route published |
| 8.A.4 | GET /metadata → 200 with string name and description, plus nullable readme_content, version, author, documentation_url |
| 8.A.5 | GET /schema → 200 with action, observation, state, each a JSON Schema object. state may be the fixed base-State schema |
| 8.A.6 | POST /mcp with body {} → HTTP 200 carrying "jsonrpc":"2.0". Never 4xx for a protocol error |
| 8.A.7 | Mode consistency: if /reset appears in paths, /step and /state must too; if it does not, neither may |
| 8.A.8 | POST /reset accepts an absent body, {}, or {"seed":int≥0,"episode_id":str≤255,…}; returns the four-key envelope in order with metadata always present; seed < 0 → 422; non-JSON Content-Type → 422 |
| 8.A.9 | POST /step accepts {"action":object,"timeout_s"?:number>0,"request_id"?:string≤255,…} with the action wrapped; returns the same envelope with reward a number or null |
| 8.A.10 | GET /state returns a flat object with at least episode_id (string|null) and step_count (int ≥ 0) |
| 8.A.11 | Action-validation failure on /step → 422 with action-relative loc; envelope-validation failure → 422 with loc prefixed "body" |
| 8.A.12 | WS /ws accepts an upgrade at exactly that path, negotiating no subprotocol, speaking text frames only |
| 8.A.13 | On /ws, accept the five client types, and reject extra envelope keys with VALIDATION_ERROR |
| 8.A.14 | On /ws, emit the four server types, with reward uncoerced and metadata omitted when empty |
| 8.A.15 | Maintain per-connection session state: two steps in one connection observe accumulated state, and reset is not required first |
| 8.A.16 | Emit only the seven WSErrorCode strings, with their declared extra keys |
| 8.A.17 | Reject over capacity by accepting the upgrade first, then one CAPACITY_REACHED frame, then closing. Never fail the handshake |
| 8.A.18 | On {"type":"close"}, send no reply frame and close with 1000, empty reason |
| 8.A.19 | POST /mcp and WS /mcp implement the four methods; anything else → -32601. Emit {"jsonrpc","id"} then exactly one of error/result |
| 8.A.20 | Register the six Task API routes. 501 is a conforming answer; env_name mismatch (case-insensitive) → the second 404 |
| 8.A.21 | Emit content-type: application/json on every JSON response. No CORS headers, no auth headers, no custom headers |
| 8.A.22 | Starlette-compatible defaults: trailing slash → 307 with location; wrong method → 405 with allow; unknown path → 404 {"detail":"Not Found"} |
| 8.A.23 | Exit cleanly on SIGTERM within 10 s |
The twenty client requirements
Published here because they were not published anywhere. Sixty comments in
the .c and .h files of this tree cite MUST 8.B.n — in src/client/, in
src/proto/client_codec.c, in tests/t_client.c, and in the INSTALLED header
a stranger reads after make install. Until this section existed, a reader
who followed one arrived nowhere. This is the client half of the protocol: the
half a person writing an agent needs, and the half no conformance tool checks.
Nothing below is checked by openenv validate --url, which only ever talks to
a server. What checks them here is tests/t_client.c, which has a case named
after each of the ones this implementation can be wrong about. The code they
describe is tour step 8b, src/proto/client_codec.c — a pure
function with no socket in it.
And a counted artifact now stands behind these rows, the way
tour/01_minimal.c ↗ stands behind the 8.A ones.
tour/03_client.c ↗ (tour step 8c) is the client
half hand-written with src/wire/ and nothing from src/proto/.
It is 73 statements of client protocol, fenced so make lines-tour measures
them. It drives the genuine Python reference to done, and it sends
byte-for-byte the same client frames the library client does (interop.sh
oracles 3c and 3d). So these twenty MUSTs are measured and checked, not just
asserted.
| # | A minimal conforming OpenEnv client MUST |
|---|---|
| 8.B.1 | Derive the WebSocket URL as rstrip("/") → scheme map (http→ws, https→wss, a bare host gets ws://) → append /ws. No query parameters, and a base URL with a path keeps it |
| 8.B.2 | Poll GET {base}/health for status 200 before connecting. Do not inspect the body |
| 8.B.3 | Open exactly one WebSocket to {ws_base}/ws, sending no Sec-WebSocket-Protocol, no Authorization, no cookie. OpenEnv has no authentication of any kind |
| 8.B.4 | Send only masked TEXT frames (opcode 0x1, RFC 6455 §5.1) containing JSON objects. Never binary; never a non-object JSON payload, which kills the session |
| 8.B.5 | Auto-reply to a server Ping with a masked Pong carrying the same payload |
| 8.B.6 | Keep client→server frames under 16 MiB (uvicorn's ws_max_size) |
| 8.B.7 | Operate strictly lock-step: one request frame, then block for exactly one response frame. No pipelining, and no correlation ids exist to pipeline with |
| 8.B.8 | Send {"type":"step","data":{…action fields…}} — the action is the direct value of data, not wrapped under "action". That wrapping is HTTP-only |
| 8.B.9 | Send {"type":"state"} and {"type":"close"} with no data key. Adding one is a VALIDATION_ERROR |
| 8.B.10 | Never add extra keys to the envelope — no id, no seq, no version. All five server-side models are extra="forbid" |
| 8.B.11 | Branch on data.code, not on data.message. Treat CAPACITY_REACHED, FACTORY_ERROR and SESSION_ERROR as terminal and the other four as recoverable |
| 8.B.12 | Read reward and done from the top level of data, never from inside observation — the nested dump excludes both keys, so they are absent in there and a lookup hands back your own default rather than anything the server sent |
| 8.B.13 | Accept reward as null, true, false, an integer or a float. A double-only field silently invents a number nobody sent |
| 8.B.14 | Treat top-level metadata as optional on the WebSocket and nullable on HTTP; fall back to observation.metadata |
| 8.B.15 | Tolerate unknown keys inside observation. Servers add environment-specific fields freely — that is what an observation is |
| 8.B.16 | Treat any socket close as terminal and reconnect for a fresh session. There is no resume, no session id and no replay |
| 8.B.17 | Send {"type":"close"} best-effort before closing, and await nothing |
| 8.B.18 | If speaking /mcp: send exactly {jsonrpc, method, params?, id?} and nothing else; always give an id; never send a batch array; accept both inputSchema and input_schema in a tools/list result; expect HTTP 200 for every JSON-RPC error |
| 8.B.19 | Do not assume a non-2xx HTTP response is JSON — a 500 is text/plain Internal Server Error |
| 8.B.20 | Set content-type: application/json on every POST body, including {} |
Three of these are where a plausible client is wrong rather than incomplete:
8.B.12, 8.B.13 and 8.B.15. ../src/client/README.md
argues each one at the length it deserves.
tests/t_conform.c re-implements criteria 1–6 exactly as
openenv validate --url does, and then prints the line the official suite has
no equivalent of:
$ V=1 ./build/rel/tests/t_conform
- conf_01_openapi_version_available
- conf_02_health_endpoint
- conf_03_metadata_endpoint
- conf_04_schema_endpoint
- conf_05_mcp_endpoint
- conf_06_mode_endpoint_consistency
validate --url: 6/6 required criteria passed, profile openenv-http/1.x
--- beyond the official suite: the WebSocket no criterion
opens, and the episode that exists only there ---
- the_handshake_the_official_suite_never_performs
- an_episode_round_trip_and_the_mirror_that_cannot_do_it
- the_error_frame_vocabulary_a_client_switches_on
- a_full_server_answers_101_and_then_refuses_in_a_frame
- a_close_message_is_answered_with_silence_then_a_close_frame
- the_two_encoders_disagree_about_one_observation
ok t_conform: 151 checks, 0 failed
The official conformance suite never opens a WebSocket. Every criterion it checks is HTTP. The episode — the thing OpenEnv exists for — is unverified by it. That is the sharpest single fact about the state of this specification, and it is why the six checks above are followed by six more.
What is deliberately absent
Half the lesson, and it has its own document:
NOT-THE-PROTOCOL.md.
- no authentication, no CORS, no TLS
- no protocol version anywhere on the wire
- no action or observation spaces —
/schemais the whole shape description - no legal-move or action-mask concept
- no turn-taking or player identity
- no session id, no correlation id, no streaming, no server-initiated frames
- no episode state machine
Reading on
WARTS.md | every reference oddity a compatible server must reproduce, with its observed bytes — generated from the source |
GAPS.md | every question this document could not answer — generated from the source |
NOT-THE-PROTOCOL.md | every refusal, with the reference's bytes for each |
PROVENANCE.md | how all of the above was derived, and the fifteen oracles that grade it |
TOUR.md | the reading path through the implementation |
../src/proto/types.h ↗ | this document as a header, and the place it is enforced |