miniopenenv

examples/README.md → html

examples/ — the other end of the socket

grep -in 'counter\|amount\|last_note\|echoed' examples/oe_agent.c   # -> banner only
grep -rn 'proto/\|client/' examples/oe_probe.c                      # -> nothing

envs/ is what an environment author writes. This directory is what somebody driving an environment writes, and the two programs here take deliberately opposite approaches to the same conversation.

UsesShows you
oe_probe.csrc/wire/ only — sockets, HTTP, RFC 6455, JSONthe wire, byte by byte, with the rule behind each byte printed beside it
oe_agent.c<openenv/openenv.h> and <openenv/embed.h> onlywhat a consumer writes after make install — no wire at all

Neither is built on the other, and neither knows anything about any environment.


§ 1 · oe_probe — the protocol, slowly and out loud

oe_probe — the protocol, slowly and out loud

A frame dumper for any OpenEnv server: ours, the Python reference, or something a third party wrote. Every byte it sends and every byte it receives is printed, and beside each part is a line naming what that part is and which rule put it there.

oe_probe [URL] [--health] [--metadata] [--schema] [--episode]
         [--steps N] [--action JSON] [--past-done]

With no mode flag it runs all four, in that order, which is the whole tour.

It is deliberately not built on our client. A frame dumper that showed you its own abstractions would be showing you the wrong thing — what scrolls past is the wire, not our idea of the wire. That is why it includes from src/wire/ and nothing from src/proto/ or src/client/, and the second grep at the top of this file is that claim.

Read --episode top to bottom and WebSocket stops being a black box. The handshake is four headers and one SHA-1. A frame header is at most fourteen bytes, printed here in hexadecimal with the meaning of every bit beside it. It is ../docs/TOUR.md step 13b for exactly that reason — the gentler on-ramp to reading src/wire/ws.c.

It also makes the README's transcript falsifiable by the reader in under a minute, which is the real reason it is in the repository. A claim about bytes that you cannot reproduce is a claim you have to take on trust.

Two things it refuses, by name rather than by a confusing failure: TLS (https:// and wss://), and any environment knowledge at all. The action it steps with is {} unless you pass --action, because an action shape is the environment's business and GET /schema is where it is published.

One limit it states rather than hides: a single 64 KiB input buffer, so a server frame larger than that is reported and ends the run. The library's own reader grows and refuses at OE_WS_MAX_FRAME instead. A demonstration should say which of the two it is.


§ 2 · oe_agent — the claim this repository exists to make, as a program

oe_agent — the claim this repository exists to make, as a program

A random agent that has never heard of your environment. It fetches GET /schema, reads the action half, synthesises actions that satisfy it, and drives episodes to done over WS /ws.

The transcript below stops at the end of the episode. The program then prints a reward census and a paragraph on what a schema-only agent cannot discover — cut here for length, and reproduced by running it.

$ ./build/rel/bin/oe_agent http://127.0.0.1:8936 --episodes 1 --max-steps 2
oe_agent — a random agent that has never heard of this environment.
  target      http://127.0.0.1:8936
  it knows    GET /schema, and nothing else
  it contains no field name and no fallback for any environment

--- what GET /schema says an action is -----------------------------------
  title: EchoAction
  metadata       object     the framework's, not the environment's — left alone
  message        string     no default, therefore REQUIRED

--- episode 1 ------------------------------------------------
  reset  -> done=false
  step 1   {"message":"todf"}
           -> reward null           done=false
  step 2   {"message":"rly"}
           -> reward null           done=false
  2 steps without `done`. Not an error: nothing in the protocol
  bounds an episode, and no environment is obliged to end one.

Run it against all three of envs/ and watch it not care. That output is against envs/echo; nothing in the program mentions message.

There is no fallback action. When /schema is not enough to build a valid action the agent says so, loudly, and stops. An agent with a hardcoded fallback proves nothing about the protocol and everything about the one environment it was tested against.

On its randomness. A hand-written splitmix64 seeded by --seed, which defaults to a constant, so two runs against the same server produce the same episode. That is a feature: a reinforcement-learning demonstration you cannot replay is a demonstration you cannot debug. The one place in this conversation where unpredictability is a security property — the WebSocket masking key — is inside the library and comes from the kernel. That is why C's rand is banned repository-wide (make check enforces it) and this file still gets to be random.

tools/interop.sh oracle 3a points this program at the genuine upstream Python server and asserts it reaches done. That is the only test in the tree that puts our client in front of a server we did not write.


§ 3 · Not here

Not here

No environment. No server loop. No protocol decisions of any kind — both programs are consumers, and everything they rely on is either src/wire/'s public surface or the two installed headers.

§ 4 · See also

See also