miniopenenv

docs/NOT-THE-PROTOCOL.md → html

Not the protocol

This page lists what a conforming OpenEnv implementation does not have to do, with the reference's own captured bytes beside each claim. The reference — huggingface/OpenEnv, the Python implementation this repository was captured from — is quoted so that "not protocol" is a measurement rather than an opinion. And that is the point of the list: the sharpest way to show where the protocol ends is to name what lies outside it. Refusals are pedagogy.

Three different things are on this page, and confusing them is the mistake this document exists to prevent:

KindMeans
[absent]it is not on the wire at all. There is nothing to implement, and the absence is the lesson
[out of scope]it is on somebody's wire, and we refuse to reproduce it, because reproducing it would be inventing protocol
[divergent]we produce different bytes from the reference on purpose. Each one costs something, and the cost is stated

Related: WARTS.md is the opposite list — reference behaviour we do reproduce even though nobody would have designed it. GAPS.md is the third category, where nobody decided at all. A WART-nn or GAP-nn below is a numbered entry in those two ledgers.


§ 1 · [absent] — there is nothing there

[absent] — there is nothing there

Each row below was established by reading captured traffic, not by reading documentation. Start with the strongest available evidence. Seven distinct header names appear across all 78 captured HTTP responses, and that is the complete set.

$ python3 -c '...print every header name in the corpus...'
http cases: 78
every header name seen: ['allow', 'connection', 'content-length',
                         'content-type', 'date', 'location', 'server']

Four of them — date, server, content-length, connection — are on every one of the 78 HTTP responses. content-type is on 77, the exception being the 307 with an empty body. allow appears on the four 405s, and location on that one 307. A typical response, complete, from case 0:

HTTP/1.1 200 OK
date: Tue, 28 Jul 2026 09:45:37 GMT
server: uvicorn
content-length: 20
content-type: application/json
connection: close

Everything in the table below is either absent from that list or absent from every payload.

What people expectThe evidence it is not there
authenticationwww-authenticate is not in the header set, and no captured request carries or provokes an authorization exchange
CORSno access-control-* header exists in the set, including on the preflight-shaped OPTIONS /health — which is answered 405 (case 11)
a protocol versionnothing in any header or payload names one. openenv.yaml has spec_version: 1 and that file never reaches a socket. GET /openapi.json's info.version describes the document
TLSnothing in the reference's server or client stack terminates it. The reference's own Spaces provider answers this by running a local plaintext proxy and pointing the client at it
a session idsessions are per-WebSocket-connection, keyed by a server-side UUID that is never transmitted. /mcp's openenv/session/create returns one, and it names a different kind of session — see below
a correlation idPOST /step accepts a request_id and never echoes it anywhere. GAP-07
action or observation spacesno Gym-style space objects exist. GET /schema is the entire machine-readable shape description
legal moves / action masksConnect4's legal_actions is an ordinary environment field with no protocol meaning. Nothing reads it
turn-taking or player identityno field, no message type, no header
terminated / truncatedone done, and that is the whole terminal vocabulary
an episode state machinestep before reset is accepted; step after done is accepted, repeatedly; two resets are accepted. GAP-01, GAP-02
streaming, or any server-initiated framestrictly one request, one response. There is no state machine to hold a partial answer in
an agent-facing rollout pathno consumer in the ecosystem drives an OpenEnv environment over JSON-RPC. Every /mcp exchange in the corpus was provoked by our own capture script; no shipped client sends these bytes — see below
rubrics, evals, harnesses, trainers, the CLI, openenv.yaml, the Hub integration, container providers, the Gradio UIzero wire footprint, all of it. None of it changes a byte a non-Python client sees

The last row is the largest thing on this page by volume, and the least interesting on the wire. That is exactly the point this repository was built to make.

And the second-to-last row is the strongest one here, because it is about the architecture's headline feature. OpenEnv documents a dual API boundary — a trainer door and an agent door — and the agent door has no traffic. That is established by reading the consumers rather than the wire, so it is the one row above with a different kind of evidence. It deserves to be spelled out:

ConsumerHow it reaches a toolMCP bytes on a socket
TRLinspect.getmembers over the wrapper class, executed in-process (grpo_trainer.py:645, :1986)none
verifiersits contract="mcp" branch builds MCPToolClient, whose default door is WS /ws (mcp_client.py:157 use_production_mode = False); its v1 taskset sends client.step({"type": "list_tools"}) outrightnone
prime-rlno mcp or openenv token in src/ at allnone
openenv collect — the reference's own agent-rollout entry pointsession.list_tools() and session.call_tool() are Python method calls (harness/__init__.py:493, :540), and the step adapter forwards them to self._client.step(action) (:368)none

So a server that refused tool tables outright would still be byte-compatible with every shipped consumer. We implement the agent door anyway, and the next section is that decision with its evidence. A boundary this repository documents and cannot show is a diagram, not an architecture.


§ 2 · The refusal that did not survive its own evidence

The refusal that did not survive its own evidence

This page used to refuse MCP (Model Context Protocol) tool tables outright: there is no OpenEnv-defined shape for one, so emitting any shape would be inventing protocol. The refusal was published with its evidence, the evidence was re-examined, and it did not survive. It has been replaced by three narrower refusals, further down, which are worth more precisely because each one names the bytes it declines.

What killed it was its own byte-identity claim. The old entry said our canned -32603 was byte-identical to what the reference emits for envs/counter's Python twin. It is not. And the corpus — the captured reference traffic in tests/fixtures/reference-corpus.json — had never been shown the input that proves it: a tools/call carrying params. The reference's own probe_env, which has no tool surface of any kind:

$ curl -s -X POST :8901/mcp -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{}}'
{"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Missing 'name' in params","data":null}}
$ curl -s -X POST :8901/mcp -d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"x"}}'
{"jsonrpc":"2.0","id":3,"error":{"code":-32603,"message":"Environment does not support MCP","data":null}}

The dispatcher reads params["name"] at http_server.py:967 and answers about the params at :970-975 — above the mcp_client is None and mcp_server is None test at :977. We answered -32603 to both, so the first row was one input with a wrong code and a wrong message, in the single case the refusal cited as its proof. WART-27 is the branch that fixes it. Corpus cases 83, 84 and 86 are the rows that now pin it, on an environment with tools and on one without.

What a tool surface is

Three keys, and one spelling per door. Live from build/rel/bin/echo_tools, which is the reference's own echo_env in C. It has two tools and no action fields at all, because its tools are its surface. The trainer door first (POST /step, and {"type":"step"} on /ws):

$ curl -s -X POST :8931/step -H 'content-type: application/json' \
       -d '{"action":{"type":"list_tools"}}'
{"observation":{"metadata":{},"tools":[{"name":"echo_message","description":"Echo back the
provided message.","input_schema":{"additionalProperties":false,"properties":{"message":
{"type":"string","description":"The message to echo back"}},"required":["message"],
"type":"object"}}, …]},"reward":null,"done":false,"metadata":null}

and the agent door (POST /mcp, WS /mcp, {"type":"mcp"} on /ws):

$ curl -s -X POST :8931/mcp -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"echo_message","description":"Echo back
the provided message.","inputSchema":{ …the same schema… }}, …]}}
$ curl -s -X POST :8931/mcp -d '{"jsonrpc":"2.0","method":"tools/call","id":2,
      "params":{"name":"echo_message","arguments":{"message":"Hello!"}}}'
{"jsonrpc":"2.0","id":2,"result":"Hello!"}

name, a sentence, an argument schema. A tools/call answer is the tool's return value, bare — {"result":"Hello!"} is a whole reply, and so is {"result":42}. Both shapes are the reference's own FastMCP-free code. http_server.py:945-958 hand-writes the camelCase three on /mcp. And mcp_types.py:179-195 — extra="forbid", exactly name/description/ input_schema — is the snake_case three the step door serialises.

Why the spelling changes with the door, and why that is correctness rather than taste. OpenEnv's own agent-side converter reads inputSchema and has no snake fallback (llm_client.py:463, :485). Fed the trainer door's payload it answers:

$ python -c 'from openenv.core.llm_client import _mcp_tools_to_openai; …'
{"type":"object","properties":{},"required":[]}

An agent pointed at the wrong spelling is not slightly wrong — it is told the tool takes no arguments. Meanwhile the only tool-table client that ships, MCPToolClient, reads payload.get("input_schema", payload.get("inputSchema", {})) (mcp_client.py:80) and accepts either. One door has a reader that demands camel. The other has a model that declares snake. Nothing anywhere reads both spellings on one door. That is the whole argument.

And the two doors disagree about what a step is. One socket, one environment instance, eleven frames — the reference on the left, this implementation on the right, same script:

                            reference echo_env :8902        build/rel/bin/echo_tools
state (fresh)               step_count 0                    step_count 0
step list_tools             observation with `tools`        observation with `tools`
state after list_tools      step_count 1                    step_count 0   <- divergence 7
step call_tool              observation with `tool_name`    observation with `tool_name`
state after step call_tool  step_count 2                    step_count 1
mcp envelope tools/call     {"type":"mcp","data":{…}}        {"type":"mcp","data":{…}}
state after mcp call        step_count 2   <- unchanged     step_count 1   <- unchanged
mcp envelope tools/list     {"type":"mcp","data":{…}}        {"type":"mcp","data":{…}}
state after mcp list        step_count 2   <- unchanged     step_count 1   <- unchanged
reset                       observation                     observation
state after reset           step_count 0, NEW episode_id    step_count 0

The trainer door counts and can carry reward and done. The agent door runs the same tool against the same environment instance and can do neither. On the reference, the first nine frames all report one episode_id, and a new one appears only after reset. That is what makes this a proof rather than a coincidence: the agent-door calls really did run against the instance the trainer door was stepping. Ours reports a fixed id, because rand is banned outright here. So the C half of the claim is pinned by tests/t_replay.c instead — frame by frame, including the stepwise bool an author reads inside the handler.

What a tool is NOT is the same lesson this page makes about the envelope (the four-key object every observation travels in). No capability negotiation, no initialize, no session, no cursor, no outputSchema, no annotations, no title, no icons, no pagination. A name, a sentence, an argument schema and a function. And the published schema is advertisement — nothing validates arguments against it, because the branch we emit does not (GAP-21, measured: a declared integer accepted "seven" and the tool ran).


§ 3 · [out of scope] — on somebody's wire, and refused

[out of scope] — on somebody's wire, and refused

The three refusals below are what is left of the old one. They are the same argument at a tenth of the width: we decline bytes whose provenance is a Python library rather than an OpenEnv decision.

FastMCP's nine-key Tool dump

Every shipped MCPEnvironment sets mcp_client, so this is what tools/list answers on the reference's /mcp today (corpus case 40, first tool only):

{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"echo_message","title":null,
"description":"Echo back the provided message.","inputSchema":{"additionalProperties":false,
"properties":{"message":{"type":"string","description":"The message to echo back"}},
"required":["message"],"type":"object"},"outputSchema":{"properties":{"result":{"type":"string"}},
"required":["result"],"type":"object","x-fastmcp-wrap-result":true},"icons":null,
"annotations":null,"meta":{"fastmcp":{"tags":[]}},"execution":null}]}}

Those nine keys are list(mcp.types.Tool.model_fields) in declaration order — the MCP specification's model, dumped by t.model_dump() at http_server.py:936. Three of them carry the tool. Four are null on every tool the reference ships. The last two carry fastmcp's own bookkeeping. And one key is wrong, by a single missing keyword argument:

$ python -c "import mcp.types as T; f=T.Tool.model_fields['meta']; print(f.alias)"
_meta
$ #  t.model_dump()                 -> {…,"meta":{"a":1},"execution":null}
$ #  t.model_dump(by_alias=True)    -> {…,"_meta":{"a":1},"execution":null}

The specification's own key is _meta; the reference publishes meta because that call omits by_alias=True. So the nine-key shape is neither OpenEnv's nor MCP's. x-fastmcp-wrap-result is a fastmcp 3.4.4 keyword inside a published JSON Schema, and meta.fastmcp is that library signing its own output. A C implementation that copied them would have stamped one Python library's version-specific serialisation bugs "OpenEnv". That is exactly the invention the original refusal was right to fear, and exactly one branch away from where it aimed.

We emit http_server.py:945-958 instead: the same server's own hand-written three keys, reachable with no FastMCP object in the process at all (corpus cases 80–82, captured from a synthetic mcp_server-only environment). Case 40 is EXPECTED-DIVERGENT in every replay run, and the classifier prints that paragraph rather than a port number.

FastMCP's CallToolResult envelope

The matching tools/call reply (corpus case 41):

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"Hello!",
"annotations":null,"meta":null}],"structured_content":{"result":"Hello!"},
"meta":{"fastmcp":{"wrap_result":true}},"data":"Hello!","is_error":false}}

Read that beside the tool dump above: inputSchema is camelCase and structured_content is snake_case, in the same server, in adjacent replies. That used to be quoted here as proof that the specification has no single answer. It is not. It is two named lines serialising two Python types:

$ python -c "…mcp.types.CallToolResult.model_fields…"
['meta', 'content', 'structuredContent', 'isError']
$ python -c "…dataclasses.fields(fastmcp.client.client.CallToolResult)…"
['content', 'structured_content', 'meta', 'data', 'is_error']

MCP's own result type is camelCase. fastmcp's client-side one is a @dataclass, and _make_json_serializable reaches it through its __dict__ (http_server.py:95-123). So the field names go on the wire as Python spells them. Keep the bytes, reverse the inference: "nobody knows the shape" is a shrug, and "these two lines are bugs, here is the one-command proof" is a finding.

Refused on three grounds, each measurable:

Spec-MCP: initialize, and the whole lifecycle behind it

No initialize, no notifications/initialized, no capability negotiation, no SSE, no Mcp-Session-Id, no resources/*, prompts/*, completion/*, logging/*, roots/* or sampling/*, no pagination cursor, no MCP-Protocol-Version handling. Of the specification's methods OpenEnv implements exactly two — tools/list and tools/call — beside two openenv/… extensions the specification does not have. We implement the same two and decline both extensions.

The argument is not that the specification is large. It is that the reference fails a genuine MCP client and so do we, identically:

$ curl -s -X POST :8902/mcp -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{…}}'
{"jsonrpc":"2.0","id":0,"error":{"code":-32601,"message":"Method not found: initialize","data":null}}
$ curl -s -X POST :8931/mcp -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{…}}'
{"jsonrpc":"2.0","id":0,"error":{"code":-32601,"message":"Method not found: initialize","data":null}}

ping, resources/list, prompts/list and notifications/initialized are -32601 on both, and a bare GET /mcp is 405 on both. Three real clients were pointed at the reference: the official mcp SDK over streamablehttp_client, the same SDK's sse_client, and fastmcp's own Client. None of them reached a tool call — two died on initialize, and the SSE transport died on that 405 before sending anything. The single most quotable consequence: fastmcp 3.4.4's own client cannot connect to a server built on fastmcp 3.4.4.

interop/interop_specmcp.py is that as a test: oracle 4. An oracle here is an independent judge, usually upstream's own code, that grades this implementation — and this is the only one where passing means a peer failed. RFC 003:74-77 agrees, calling /mcp a deliberately non-conformant custom transport. What the reference documents and the experiment falsifies is docs/source/tutorials/mcp-environment.md:13, which says an MCP client such as Claude Desktop can plug into it. Naming that is the honest version of "we do not implement spec-MCP".

openenv/session/create

openenv/session/create returns a UUID. In the reference, that UUID names an environment instance stored in the same table the WS /ws capacity check reads. The entry has no timeout by default and no socket to hang up, and the reaper returns immediately when the timeout is None. Ten unauthenticated POSTs against a freshly started reference:

$ for i in $(seq 1 10); do curl -sX POST :8912/mcp \
      -d "{\"jsonrpc\":\"2.0\",\"method\":\"openenv/session/create\",\"id\":$i}"; done
 1  {"jsonrpc":"2.0","id":1,"result":{"session_id":"fb930438-…"}}
 …                                                                (2 through 7 likewise)
 8  {"jsonrpc":"2.0","id":8,"result":{"session_id":"e03740ee-…"}}
 9  {"jsonrpc":"2.0","id":9,"error":{"code":-32000,"message":"Server at capacity: 8/8
     sessions active. Cannot accept new connections.","data":{"active_sessions":8,"max_sessions":8}}}

$ websockets.connect('ws://127.0.0.1:8912/ws')     # first frame, before any request
{"type":"error","data":{"message":"Server at capacity: 8/8 sessions active. Cannot accept
 new connections.","code":"CAPACITY_REACHED","active_sessions":8,"max_sessions":8}}

$ curl -sX POST :8912/reset -d '{}'                # and yet
{"observation":{"metadata":{"status":"ready","message":"Echo environment ready!"}},"reward":0.0,…}

Eight succeed and the ninth does not. The WebSocket transport is then dead for the life of the process, while POST /reset keeps answering 200. An unauthenticated HTTP route that permanently disables the WebSocket transport and leaves the stateless mirror working is a more interesting sentence than "a DoS". The asymmetry is the teaching point. RFC 003 — the RFC that authorised /mcp — lists "no session management" among its own limitations. So the extension contradicts the document that permitted the endpoint.

WART-17 names the hazard at the line in src/proto/jsonrpc.c that would hand a session id to a table. GAP-19 in src/server/mcp.c is our host declining: we answer -32000 "Session creation is not supported on this transport" with data:null, because this seam owns no table, no random source and no clock. That is a divergence in the whole sentence rather than in one field. There is no server state in which the reference emits our message, and none in which we emit theirs — which is why corpus case 42 is listed as divergent rather than matched.

What the refusal costs, and it is small: an MCPToolClient with use_production_mode = True cannot drive our /mcp door, because _ensure_production_session creates a session and then passes its id to tools/list (mcp_client.py:201-213, :245-249). That flag is set by no constructor and by exactly three lines in the whole reference tree — one example file and two tests. The client's default door is WS /ws, which drives us fine. So does any raw JSON-RPC client, because session_id is optional everywhere else. tools/interop.sh oracle 2e is the genuine client completing both list_tools and call_tool against envs/echo_tools.c with the session extension refused throughout.

Production mode — served, and off by default

This section used to argue a refusal. It no longer can, and that is the point of the conformance arc's last step. The route table's simulation_only column is now read at runtime: oe_serve_opts.production, and the production parameter of oe_http_handle, select the reference's ServerMode.PRODUCTION (register_routes(app, mode=...)). The route set was mapped empirically in reference/notes/WIRE-CAPTURE.md §"Simulation vs production mode". In that mode the three rows /reset, /step and /state cease to exist, and GET /openapi.json omits them from paths. A request to one is the generic {"detail":"Not Found"} 404, answered before the method is checked — so POST /reset with the correct verb is a 404 and not a 405. WS /ws is untouched, so the transport episodes actually run on survives while the stateless HTTP mirror does not. Corpus cases 43, 44 and 45 (port 8903) were captured against this mode and now replay byte for byte. The production /openapi.json (case 47) is one of the fifteen exchanges the replay still reports as EXPECTED-DIVERGENT — and it is there for the minimal-document reason case 4 is, not because of the mode. docs/PROTOCOL.md states the same behaviour in the route table there.

What remains true, and is the only reason this is still worth a heading: the mode is unreachable from any shipped reference entry point. grep -rn "ServerMode.PRODUCTION" over the reference's src/ and envs/ returns nothing. Its two public factories — create_app() and create_fastapi_app() — accept no mode argument, and both register the default. So it is a real, observable protocol mode that no environment the reference ships can actually be in. The corpus captured it against a purpose-built server (interop/prod_env.py, which re-registers the counter through register_routes(..., ServerMode.PRODUCTION)). This project serves it because the column is a protocol fact, and a fact the build can enforce should not sit in a comment. But simulation is the default, which is what every shipped environment on either side runs.

The date and server headers

We emit neither. date needs a clock, and src/proto/ may not read one — tools/check.sh rule 14 fails the build if it acquires the ability. server: uvicorn would be false. Every other header in the captured responses we reproduce exactly.


§ 4 · [divergent] — different bytes, on purpose, at a cost

[divergent] — different bytes, on purpose, at a cost

Seven, and each is annotated at the line that makes it.

1. Non-minimal WebSocket frame lengths — we refuse, the reference accepts

RFC 6455 §5.2 says a length under 126 must use the 7-bit form and a length under 65536 must not use the 64-bit form. Two spellings of one number is an ambiguity, and an ambiguity on a wire is somebody's parser differential.

Verified live: a text frame sent with the header 81 FE 00 02, and again with the 127 form, is answered normally by the reference. We answer close 1002 non-minimal 16-bit length and hang up.

This is the one framing rule where we refuse traffic the implementation being reproduced serves. The RFC is on our side and we keep the refusal. src/wire/ws.c, rule 4.

2. A WebSocket version mismatch — 426 against the reference's 400

The reference answers:

400 Bad Request
content-type: text/plain; charset=utf-8

Failed to open a WebSocket connection: invalid Sec-WebSocket-Version header: 7.

We answer 426 Upgrade Required carrying Sec-WebSocket-Version: 13. That is the entire point of 426 (RFC 6455 §4.4): it tells a client with a different version what to retry with. The bytes are ours and not a reproduction, and src/wire/ws.h says so at the declaration.

3. OE_WS_MAX_FRAME — 256 KiB against the reference's 16 MiB

Inbound at a server only. The number is chosen against its product with OE_MAX_CONNECTIONS: 64 × 16 MiB is a gigabyte of attacker-directed residency on a single-threaded process.

It costs something and the cost is measured. The genuine upstream client does not fragment, so a single action over the cap loses the message and the connection with close 1009. Observed against both servers: a 100 KB note is accepted by ours and by the reference. A 300 KB one is accepted by the reference and closes ours. tools/interop.sh oracle 2c pins exactly that against a live upstream client, so the day somebody raises the number the test says what changed.

A client gets 512 KiB (OE_WS_MAX_FRAME_CLIENT) — twice the server's, and no more than twice. A client does not choose what it is sent. One shipped upstream environment ships 100,800 integers in a single unfragmented message (403,316 bytes, measured), so the server's number would break it on the first frame. But the client kept 16 MiB until this was measured, and 16 MiB was a promise about residency where a caller needs one about parsing. A parse tree costs up to 128.23 bytes of arena per byte of source — an array of [ chains at depth 62, the worst of the shape families swept (MEMORY.md is the arena model). So the document a caller actually got ran from 1.05 MB to 4.19 MB depending on its shape, and the error named a constant the caller had never been shown. The cap is now that arena divided by the measured multiplier: 128 MiB / 256.

That multiplier was 128 first, from a sweep that varied one family's inner length and never its depth — and 128 is below 128.23. So for a while the division was exact, the static assertion passed, and the deep shape was still refused with OE_ENOMEM at 523,775 bytes over a real socket. Re-bisected over the same socket at the corrected pair, all five families tried — long string, dense 1-digit, dense 3-digit, [[1],…] and depth-59 chains — stop at 524,288 bytes and answer the advertised OE_ETOOBIG. What it costs: a string-shaped payload of up to 4 MB used to be delivered and is now refused, and the per-handle arena ceiling doubled to 128 MiB. That is the price of a number that holds for every shape that has been tried, rather than only the cheap ones.

4. OE_WS_MAX_MESSAGE_SERVER — 1 MiB against the reference's 16 MiB

The reassembled total, at a server only. The value is OE_HTTP_MAX_BODY deliberately: the same action document meets the same ceiling whichever transport carries it. Before this constant existed, a server read the CLIENT's number — 16 MiB at the time — and one silent socket could park that much indefinitely by opening a fragmented message and never sending FIN. Measured on envs/echo: 40 sockets holding 8 MB each held 620 MB, with no bound but the sockets' lifetime. The client's number is 512 KiB today (divergence 3), which would have made that attack smaller and not absent. The defect was reading the wrong side's budget, not the size of it.

5. Close code 1002 where the reference sends 1009

A 64-bit frame length with the sign bit set is answered 1002 here and 1009 frame with N bytes exceeds limit of M bytes by the reference. We keep 1002 because a length with its sign bit set is a malformed header, and telling a peer to retry with a smaller number implies the number could have been legal. src/wire/ws.c, rule 5, where both columns are tabulated.

6. Integers wider than int64_t

Three bands, probed against pydantic 2.13.4:

inputreferenceours
up to int64acceptsidentical
wider than int64, up to 4300 decimal digitsaccepts — {"amount":"9"×25} is a 200 carrying 9999999999999999999999999422 int_parsing
over 4300 digits422 int_parsing_size — CPython refuses to parse the literalbyte-identical

The middle band is the whole divergence, and it is a language boundary rather than a choice. An int64_t cannot carry the value, and carrying a bignum for a number no environment declares a field for is a worse trade than naming the gap. src/proto/validate.c carries the table at the conversion.

7. Discovery does not advance step_count

On the reference, a list_tools is a step: it is routed through step() like any other action, so asking what tools exist moves the counter. Ours is a pure function of a const table and calls no environment code at all, so nothing advances. By the same rule, a call_tool naming a tool that does not exist is answered by the framework and never reaches a handler — so it does not count either.

Measured, one script, the genuine MCPToolClient driving both servers — one list_tools, two good calls, one bad one:

### the reference, envs/echo_env :8902        ### ours, build/rel/bin/echo_tools
  list_tools -> ['echo_message', …]             list_tools -> ['echo_message', …]
  call       -> 'one'                           call       -> 'one'
  call       -> 'two'                           call       -> 'two'
  call bad   -> RuntimeError: Tool 'nope' …     call bad   -> RuntimeError: Tool 'nope' …
  state      -> step_count=4                    state      -> step_count=2

Every reply the client read was identical; only the counter differs. What it costs: a trainer that counts steps sees a different number after a discovery call — one per list_tools, one per unknown tool. The reference's own mcp_types.py:10-13 says discovery "does NOT require reset() first", so counting it is arguably the reference contradicting itself. That is an explanation and not a defence.

The alternative, and why it was not taken: route discovery through env->step, which would require every environment to recognise list_tools and answer it — the exact coupling the const table exists to remove. envs/echo.c and envs/counter.c would each have grown a branch about a feature they do not have. src/proto/encode.c carries this at the encoder that writes the table.

8. The step door accepts a tool action our /schema forbids

Our GET /schema now publishes the reference's tool action model (see below), but the step door does not yet enforce it. The tool sniff (src/proto/decode.c, oe__decode_tool_action) runs before the field validator. So for any environment with a tool table, the two tool shapes bypass the action schema entirely — including its additionalProperties:false and its required tool_name.

Measured, build/rel/bin/echo_tools on one socket:

$ curl -s :8961/schema | wc -c
3061
$ curl -s :8961/schema | python3 -c 'import json,sys;print(json.load(sys.stdin)["action"]["title"])'
CallToolAction
$ curl -s -X POST :8961/step -d '{"action":{"type":"list_tools","extra":1}}'
{"observation":{"metadata":{},"tools":[{"name":"echo_message",…}]},…}      # 200

The same binary, serving envs/counter.c, answers {"type":"list_tools"} with 422 extra_forbidden on type — so the behaviour is lax only for tool-bearing environments, which is the surprising direction.

The schema half is closed, and closing it did not cost an invention. :8902/schema is 3061 bytes and its action model is the framework's CallToolAction, carrying type, tool_name and arguments. Corpus case 88 captured that document, so envs/echo_tools.c hands it over whole through the action_schema_json escape hatch. Our /schema now reproduces it byte for byte. The earlier claim here — that closing the gap meant synthesising JSON Schema we never captured — was wrong. The bytes were in the corpus the whole time. A client reading our /schema now learns exactly what the step door takes. And a real trainer's tool-discovery predicate, which keys on action.title, fires on CallToolAction — where the generator's EchoAction silently turned it off (interop/interop_verifiers_schema.py, oracle 6).

What is left, and whose it is. The behaviour: the step door still accepts the extra key and the missing tool_name that the model we now publish forbids. So a consumer that validates a request against GET /schema will reject one we accept. That row is held as reference bytes, classified EXPECTED-DIVERGENT, and closing it is item 8. GAP-22 at the sniff is the long form. It separates this environment, which quotes the captured schema, from one that leans on the generator — which still cannot describe the tool actions it accepts.


§ 5 · Also ours rather than the protocol's

Also ours rather than the protocol's

Two more places where the bytes are ours, both named at the line:

And one that is not a divergence at all, only a boundary: src/wire/arena.c is the only translation unit in the program that calls malloc. Nothing about that is OpenEnv; see MEMORY.md.