miniopenenv

envs/README.md → html

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.

§ 1 · The four, in the order to read them

The four, in the order to read them

FileWhat it addsStatements
1echo.cthe whole author contract. Two field tables, one state struct, three callbacks, one oe_env, one main45
2counter.cstate that survives a step, a reward, a done condition, and a state callback with something in it—
3rewards.cone step, and the same reward arriving as two different JSON types on the two transports—
4echo_tools.ca 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.

§ 2 · counter.c may not be improved, and that is not a style rule

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.

§ 3 · rewards.c exists to make one wart visible from a shell

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.

§ 4 · echo_tools.c is the other kind of environment: one an agent drives

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}
§ 5 · The memory rule, in the one sentence an author needs

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.

§ 6 · What the field table is, and what it is not

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.

§ 7 · Not here

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.

§ 8 · See also

See also