tour/ — the protocol, hand-written, from both chairs
make lines-tour
Three programs, one counter environment. Two are servers — 01_minimal.c
with the protocol hand-written as string literals, 02_conformant.c with the
library — and their five server frames are byte-for-byte identical on the wire.
The third, 03_client.c, is the client that drives the same environment to
done, hand-written the same way. Those comparisons are the sharpest thing
this repository has, and these files exist so that they are a measurement rather
than a paragraph.
| File | What it is | Statements |
|---|---|---|
01_minimal.c | the SERVER protocol, hand-written as string literals. Uses src/wire/ and nothing from src/proto/ | 64 of protocol + 177 of socket |
03_client.c | the CLIENT protocol, hand-written the same way — the twenty 8.B MUSTs, src/wire/ only | 73 of protocol + 391 of socket |
02_conformant.c | the same environment, written with the library the way you would ship it | 77, whole file |
$ make lines-tour
of which: THE PROTOCOL 64
of which: the socket 177
of which: neither half 13
the Python: PROTOCOL 78
the Python: the socket 0*
03_client: THE PROTOCOL 73
03_client: the socket 391
03_client: neither half 20
02_conformant: WHOLE FILE 77
Statements only — comments and blank lines are excluded from every row, because
comment density is not the comparison. The third row is the arithmetic closing:
twelve #includes and one #define fall outside both fences, so 64 + 177 is
not the file's 254 and this says where the other thirteen went. A * means
recorded, not measured — the Python rows are computed only when the reference
checkout is present, which on a fresh clone it is not.
01_minimal.c — the whole protocol, and the comparison it exists for
64 lines of C against 78 lines of Python.
The Python is tests/test_core/aca_integration_server.py in the reference
implementation — 109 lines total, 78 of protocol, zero of socket, because
uvicorn is its other 177. It is not copied here; nothing of the reference is.
To read the two side by side:
git clone https://github.com/huggingface/OpenEnv
$EDITOR OpenEnv/tests/test_core/aca_integration_server.py
That file matters because its own docstring says it "implements exactly what
GenericEnvClient (simulation mode) needs" — and it is enough for the genuine
upstream client to complete a full episode. It is the reference project's own
admission of how small the protocol is. It is just hard to notice from inside
164,000 lines.
01_minimal.c is two programs with a fence between them, and make lines
measures both halves. Read the count before you read the code. Comparing the
file's 466 lines of C against 109 lines of Python and concluding that C is
verbose is the exact mistake the fence exists to prevent. Most of those lines
are the teaching comment, and 254 of them are statements.
It uses src/wire/ and nothing from src/proto/. So when the genuine
Python EnvClient completes an episode against it, what is proved is that the
protocol is small — not that our SDK is good. Those are different claims and
this repository is careful about which one it is making.
It is not hardened, and says so in a mandatory banner
It validates no message, checks no envelope, and serves one connection at a
time. Its only limits are its own: a 64 KiB input buffer and a one-second
linger, plus OE_HANDSHAKE_TIMEOUT_MS so a silent peer cannot hold it forever.
Every other refusal it makes, src/wire/ makes on its behalf.
It binds 127.0.0.1. The library binds 0.0.0.0, because that is the container
contract and this is not the library. Nothing from tour/ is installed by
make install, and the packaging test asserts it.
Then the tour points at src/wire/limits.h: here is the 64 lines of protocol,
and here are the 200 lines of paranoia that stand between it and the internet.
02_conformant.c — the same thing with the protocol factored out
Same counter. The action's amount accumulates, the episode is done at three,
and the reward is the running total as a float. Drive both programs through
the same episode and the server frames are byte for byte identical:
$ ./build/rel/bin/01_minimal --port 8948 &
$ ./build/rel/bin/02_conformant --port 8947 &
$ for p in 8948 8947; do ./build/rel/bin/oe_probe http://127.0.0.1:$p \
--episode --steps 3 --action '{"amount":1,"note":"step"}' \
| grep '^<< {' > /tmp/frames.$p; done
$ diff /tmp/frames.8948 /tmp/frames.8947 && echo IDENTICAL
IDENTICAL
Five frames each. Nothing about the protocol changed between the two files. What changed is who writes the bytes.
Note what the number does not say
77 is more than the 64 statements of hand-written protocol in 01_minimal.c.
A library does not make the two-endpoint case smaller. It makes the other
fourteen routes free: 02_conformant.c serves sixteen routes instead of two,
eight concurrent sessions instead of one, and has no socket half to fence off at
all. Every one of its 77 statements is the environment — the state, the two
shapes, the three callbacks, the arithmetic — and not one of them is transport.
That is why the README prints 01_minimal.c beside the Python and not
envs/echo.c. Printing the 45-statement echo.c against the 78-line Python
file would be a category error. The Python file contains the protocol;
echo.c delegates it to 3,900 lines of ours. The comparison silently
swaps "the protocol is small" for "our API is small" — the exact conflation this
project exists to end.
03_client.c — the other chair, and the twenty client MUSTs made small
01_minimal.c measures the protocol from the SERVER chair. 03_client.c
measures it from the CLIENT chair. It is the client half of the protocol —
docs/PROTOCOL.md's twenty 8.B MUSTs — hand-written with src/wire/ and
nothing from src/proto/ or src/client/, fenced the same way so the count
is a measurement. 73 statements of client protocol, against 01_minimal.c's
64 of server protocol: both small, both under a hundred, both the whole of one
chair.
Its socket half — 391 statements of socket — is larger than
01_minimal.c's 177, and that is a fact about the two roles, not about the code.
A client initiates: it parses a URL, polls GET /health over HTTP, and
drives the RFC 6455 handshake. A server binds a port and answers. The
transport a client pays for is the price of no websockets library, exactly as
01_minimal.c's 177 is the price of no uvicorn.
Two proofs it is the real protocol and not a mirror, both in
tools/interop.sh and graded by a peer we did not write:
$ ./build/rel/bin/03_client http://127.0.0.1:8000
reset -> {"type":"reset","data":{}}
step 1 <- reward 1 (float) done=false
step 2 <- reward 2 (float) done=false
step 3 <- reward 3 (float) done=true
done after 3 steps.
- Oracle 3c drives it against the genuine Python reference server and it
reaches
done— the client-side mirror of oracle 2d, which does the same for the hand-written server. - Oracle 3d captures the frames it SENDS and the frames
examples/oe_agentsends through the library for the same episode, and they are byte-for-byte identical — the client-side twin of01_minimalvs02_conformant. Masking makes the raw frames differ every run, so the comparison is on the unmasked payloads, which is the only one that means anything.
Where these three sit on the tour
Steps 2, 8 and 8c of ../docs/TOUR.md.
01_minimal.c is step 2 (the server, hand-written); 02_conformant.c is step 8
(the same server with the library); 03_client.c is step 8c, beside
src/proto/client_codec.c (step 8b, the client codec) — where a reader first
meets the client. Steps 1–7 are the complete answer to "what is OpenEnv"; the
8-series is where this library, and the client that drives it, come in.
See also
../envs/README.md—echo.c,counter.c,rewards.c: the same job with the protocol entirely out of sight../docs/PROTOCOL.md— what01_minimal.cand03_client.care hand-written instances of, server and client../src/wire/README.md— the layer both hand-written files are built on, and none of which is OpenEnv../examples/README.md—oe_probe, the program that produced the transcript above, andoe_agent, the library client03_client.cis byte-diffed against