envs/ — what an environment author actually writes
grep -cE 'malloc|free|oe_arena|oe_err_name' envs/echo.c envs/echo_tools.c # -> 0, 0
make check # rule 10 enforces it
wc -l envs/*.c # 180, 113, 368, 175 (counter, echo, echo_tools, rewards)
The first command prints 0 twice, and the second is why it will keep printing
0. The second file is the interesting one. It declares a tool table,
builds a JSON object as a tool result, and reads an agent's arguments. Those
are the three places an allocator normally turns up in author code — and it
still names none.
An environment is a const table and three callbacks. No allocator, no
ownership question, no error branch, no null check, no socket, no HTTP, no JSON,
no framing, no schema code and no validator. If writing one requires more than
that, the library has failed. tools/check.sh rule 10 is the version of
that sentence a machine can decide. It greps echo.c and echo_tools.c for
four spellings: the arena type, the two C allocator functions, and the
error-name helper. If any of them appears in either file, the build fails. Both
names print on a clean run.
That is a deliberately hostile rule to live under, and echo_tools.c is the
harder file to live under it in. A tool result is a value the library has to
allocate somewhere, and the whole design of oe_tool_out is that the somewhere
is never the author's problem. It is also the only kind of claim about
ergonomics that is worth making.
The four, in the order to read them
| File | What it adds | Statements | |
|---|---|---|---|
| 1 | echo.c | the whole author contract. Two field tables, one state struct, three callbacks, one oe_env, one main | 45 |
| 2 | counter.c | state that survives a step, a reward, a done condition, and a state callback with something in it | — |
| 3 | rewards.c | one step, and the same reward arriving as two different JSON types on the two transports | — |
| 4 | echo_tools.c | a tool table: the agent half of the dual API boundary, and the one if that makes the boundary visible | — |
make lines prints the measured version of that column; envs/ totals 294
lines of code across all four.
counter.c may not be improved, and that is not a style rule
The counter exchanges in tests/fixtures/reference-corpus.json were captured
from a Python server running interop/probe_env.py, of which counter.c is a
literal port. Change it and you have not changed an example — you have
changed what the corpus means, because tests/t_replay.c would then be
diffing our bytes against a recording of some other environment.
So done is total >= 3 and not > 3. reward is float(total), a REAL,
which is why every captured reward reads 1.0 and never 1. episode_id is
episode_id or "ep-fixed", so the empty string takes the default too. Each of
those is a byte in the fixtures.
tests/counter_env.h is the same table with no main, because the replay must
link no socket and a program must not include from tests/. The two are a
pair: change one, change the other.
rewards.c exists to make one wart visible from a shell
reward is one wire field with four JSON types, and the two transports disagree
about it (WART-03). The counter environment always returns float(total), so
nothing it produces can show the difference — an integral float is the one value
both encoders agree on.
This one returns a reward of each type on request, so the same step against
the same server answers "reward":1.0 over POST /step and "reward":true
over WS /ws. The banner in the file is the shell recipe, about thirty seconds.
interop/reward_env.py is its Python twin, tests/reward_env.h is the
socket-free form, and tools/interop.sh oracle 2b drives it with the genuine
upstream client to prove the real client reads bool, int and float back as
themselves.
echo_tools.c is the other kind of environment: one an agent drives
echo.c has an action and an observation. echo_tools.c has neither worth the
name and two tools instead — echo_message and echo_with_length — which is
what an environment looks like when the peer is a model rather than a trainer.
A tool is a name, a sentence, an argument schema and a function. There is no
capability negotiation, no initialize, no session, no cursor, no
outputSchema and no annotations, and that absence is the lesson.
It is a literal port of the reference's envs/echo_env, so the same rule
counter.c lives under applies here. Corpus case 74's four frames were captured
from that server, and changing this file changes what they mean. Both tools
publish their argument schema as a literal, because the captured schema is
FastMCP's pruned one: property keys ordered type, description, no title.
The generator in src/proto/schema.c reproduces pydantic's ASCII order
instead. That is exactly what the per-tool escape hatch is for, and using it here
is what keeps the fixture honest about whose bytes those are.
The three lines worth reading are count_step, because they are the dual API
boundary as environment code:
static void count_step(void *self, const oe_tool_out *out)
{
if (out->stepwise) {
((echo_tools *) self)->steps++;
}
}
Run the same tool through the trainer door and through the agent door on one
socket and watch step_count move once:
-> {"type":"step","data":{"type":"call_tool","tool_name":"echo_message",
"arguments":{"message":"Hi!"}}}
-> {"type":"state"} <- {"episode_id":"ep-fixed","step_count":1}
-> {"type":"mcp","data":{"jsonrpc":"2.0","id":9,"method":"tools/call",
"params":{"name":"echo_message","arguments":{"message":"Hi!"}}}}
-> {"type":"state"} <- {"episode_id":"ep-fixed","step_count":1}
The memory rule, in the one sentence an author needs
Nothing this library hands you needs freeing. Everything this library hands you dies at your next call on that handle.
You declare state_size; the server allocates and zeroes that many bytes
per session and hands you the pointer as self. You never malloc and never
free, so N concurrent sessions cost you no thought at all. Every getter takes
a fallback and tolerates NULL. ../docs/MEMORY.md is the
whole model; the sentence above is the whole of what writing an environment
requires.
Callbacks return oe_err. Returning non-OE_OK is how the protocol's
EXECUTION_ERROR frame is produced — a void-returning step() would make
that frame unreachable and a whole branch of the protocol untestable.
What the field table is, and what it is not
C has no reflection, so the four-member oe_field table is this project's
entire substitute for Pydantic. It has exactly three consumers:
GET /schema, GET /openapi.json, and the request validator.
The table is not on the wire and three of its four members are. Rename the
type or reorder the struct and no Python client can tell. Rename a field and
you have silently changed a published schema, because name, json_default and
description are copied out verbatim. That is why oe_field carries a tag per
member rather than one on the struct — the boundary runs through the type.
../docs/BOUNDARY.md is the generated index.
required is derived from json_default == NULL, exactly as pydantic
derives it. One fact, one encoding, and no way for the table to contradict
itself.
Three fields you never declare and always get: metadata on every action, and
done / reward / metadata on every observation. They belong to OpenEnv
rather than to you, and watching them materialise out of framework code is the
lesson.
Not here
Anything about how those callbacks get called. That is
../src/server/, and the point of this directory is
that an author never has to go there.
See also
../docs/TOUR.md— steps 4, 5 and 7 are these three files../include/openenv/openenv.h↗ — the author's whole API, every declaration tagged../tour/README.md— the same environment written twice: once with the library and once without../examples/README.md— the other end: programs that drive an environment