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.
| Uses | Shows you | |
|---|---|---|
oe_probe.c | src/wire/ only — sockets, HTTP, RFC 6455, JSON | the wire, byte by byte, with the rule behind each byte printed beside it |
oe_agent.c | <openenv/openenv.h> and <openenv/embed.h> only | what a consumer writes after make install — no wire at all |
Neither is built on the other, and neither knows anything about any environment.
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.
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.
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.
See also
../envs/README.md— the servers these two drive../src/client/README.md— the clientoe_agentuses, and the three rules a plausible client gets wrong../src/wire/README.md— the layeroe_probeis a viewer for../docs/PROVENANCE.md— the fifteen oracles, one of which isoe_agentagainst Python