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:
| Kind | Means |
|---|---|
| [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.
[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 expect | The evidence it is not there |
|---|---|
| authentication | www-authenticate is not in the header set, and no captured request carries or provokes an authorization exchange |
| CORS | no access-control-* header exists in the set, including on the preflight-shaped OPTIONS /health — which is answered 405 (case 11) |
| a protocol version | nothing 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 |
| TLS | nothing 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 id | sessions 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 id | POST /step accepts a request_id and never echoes it anywhere. GAP-07 |
| action or observation spaces | no Gym-style space objects exist. GET /schema is the entire machine-readable shape description |
| legal moves / action masks | Connect4's legal_actions is an ordinary environment field with no protocol meaning. Nothing reads it |
| turn-taking or player identity | no field, no message type, no header |
terminated / truncated | one done, and that is the whole terminal vocabulary |
| an episode state machine | step before reset is accepted; step after done is accepted, repeatedly; two resets are accepted. GAP-01, GAP-02 |
| streaming, or any server-initiated frame | strictly one request, one response. There is no state machine to hold a partial answer in |
| an agent-facing rollout path | no 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 UI | zero 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:
| Consumer | How it reaches a tool | MCP bytes on a socket |
|---|---|---|
| TRL | inspect.getmembers over the wrapper class, executed in-process (grpo_trainer.py:645, :1986) | none |
| verifiers | its 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"}) outright | none |
| prime-rl | no mcp or openenv token in src/ at all | none |
openenv collect — the reference's own agent-rollout entry point | session.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.
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).
[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:
- Nothing reads it.
mcp_client.py:462-465takesresult["data"]when the result is a dict with adatakey and otherwise the whole result.content,structured_contentandis_errorappear nowhere in that file. - It is unsound. A result carrying
{"data":"BOOM","is_error":true}reaches the caller as the ordinary success value'BOOM', with no exception. Reproducing the envelope would mean publishing a failure channel that does not work. Failure travels as a JSON-RPCerroron the agent door and asobservation.erroron the trainer door, which is what we emit. - It is versioned exhaust.
meta.fastmcpandx-fastmcp-wrap-resultbelong to fastmcp 3.4.4, not to OpenEnv.
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.
[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:
| input | reference | ours |
|---|---|---|
up to int64 | accepts | identical |
wider than int64, up to 4300 decimal digits | accepts — {"amount":"9"×25} is a 200 carrying 9999999999999999999999999 | 422 int_parsing |
| over 4300 digits | 422 int_parsing_size — CPython refuses to parse the literal | byte-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.
Also ours rather than the protocol's
Two more places where the bytes are ours, both named at the line:
- Our close-frame reason strings are not the reference's, except one. The
ten-row table above
validate_frameinsrc/wire/ws.cprints both columns side by side, measured against the live server. Onlyincorrect maskingmatches. A close reason is prose, and RFC 6455 attaches no meaning to it. The close code is the diagnosis, and the codes match everywhere except divergence 5 above. - The message of a session-fatal
SESSION_ERRORis ours (GAP-10), because the reference's is a PythonAttributeErrorstring. Clients branch oncode, which we reproduce exactly.
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.