harness-sdk-protocol

name	harness-sdk-protocol
description	Use for Crewrift-specific harness sdk protocol recipes when optimizing a player.

Harness, SDK & wire protocol — recipes (crewrift tier)

On-demand recipes (7). Trigger→action heuristics; pull the relevant one when its situation arises.

1. Trust source code over docs; pin constants to live manifest/engine, validated by AST/Pydantic

crewrift · see related: S011 (other tier)

When you have the server/source, treat code as ground truth and docs as drift-prone. Pin gameplay constants to the live coworld_manifest.json the runtime loads, not a plan: one plan listed voteTimer=600/killCooldown=1200 while the authoritative manifest had voteTimerTicks=6000/killCooldownTicks=900, and the manifest interleaves config_schema defaults with per-variant game_config overrides so auditing one block gives the wrong value (kill-cooldown is now 500 ticks, not a stale 900). For Crewrift the Nim simulator (sim.nim) is authoritative over docs -- re-derive constants from it: 24 FPS (TargetFps=24, convert tick configs by /24); proximity gates on SQUARED distance (KillRange=20 dist^2<=400, VentRange=16 <=256, ReportRange=20 <=400); rewards completed task +1, imposter kill +10, win +100 to every player of the winning role; win conditions (alive imposters==0 or all crew tasks done => crew; alive imposters>=alive crewmates => imposters; MaxTicks during active phase => DRAW, no reward); a single A-press is processed report-body -> emergency-button -> kill/task and can short-circuit; inputs only take effect in Playing/Voting. AST-parse cited source files for constants and overwrite extracted/prose values, failing the doc on disagreement (prose archaeology produced 5 of 6 wrong button payloads and invented spurious actions like north/south/interact). Verify packet sizes, bit masks, HTTP endpoints (/healthz, /control/restart), and auth fields against the actual game SERVER (crewrift routes chat purely on isChatPacket with no follow-up button press; among_them demotes late /player connections to spectators). _{sources: auggie:5d1ff8d5-2505-4dca-af45-56d3070363e2, claude-code:067e7439-cbd1-4b26-9b3f-d054bde3aa40, claude-code:33356b24-de19-46ae-ad01-810557f4d9b1, claude-code:f70c9801-7ee7-499b-97f9-4fd0848a6b8e (+5)}

2. AmongThem/BitWorld wire is bitscreen-only (8192-byte nibble-packed 128x128); map masks via bitworld_action_index

crewrift · negative result

The AmongThem/Coworld wire perception is bitscreen-only: the server sends a 128x128 palette-indexed framebuffer packed into 8192 bytes at two pixels per byte (ProtocolBytes = ScreenWidth*ScreenHeight/2), the LOW nibble holding the even-x pixel; there is NO structured game state on the wire. This nibble packing is shared across the Python wrapper, the Go UnpackFrame, and the Nim sim's packFramebuffer, so any reimplementation must match nibble order exactly. Output is a button-mask packet sent only when the mask changes (held buttons behave like held buttons). Convert a Bitscreen button mask to a cogames action index via mettagrid.bitworld.bitworld_action_index (with BITWORLD_ACTION_NAMES) rather than hand-mapping. The global/replay viewer uses sprite v1 while the player websocket uses bitscreen v1. NEGATIVE: when a packaged Coworld policy's actions do nothing in-game, suspect wrong packet encoding -- re-check the bitscreen_v1 spec and send only valid Bitscreen v1 packets. _{sources: bitworld/among_them/players/how_to_make_a_bot.md, bitworld/among_them/players/how_to_submit_coworld_policy.md, bitworld/among_them/players/lively_lecun/ROADMAP.md, bitworld/among_them/players/lively_lecun/lively_policy.py (+1)}

3. Crewrift Sprite-v1: connect to COWORLD_PLAYER_WS_URL with no frame cap, send [0x84, mask&0x7f] only on change, one message = one atomic 24Hz frame

crewrift · negative result

Crewrift policies speak the shared Bitworld Sprite-v1 protocol over a WebSocket; the runner starts each policy with COWORLD_PLAYER_WS_URL and the policy connects, plays to game end, and exits. Connect with NO frame-size cap (websockets.connect(url, max_size=None); sprite payloads are large), expect always-binary frames, and treat the ~24 Hz stream as incremental RETAINED deltas -- keep retained tables and apply each message. Client->server input is byte 0x84 followed by one button bitmask byte ([0x84, mask & 0x7f]): up/down/left/right=0x01/0x02/0x04/0x08, A=0x20, B=0x40, Select=0x10 (unused), bit 7 reserved=0; send a packet ONLY when the held mask changes (omitted bits mean released). Chat input is 0x81 + little-endian u16 length + ASCII payload (or packet [0x01]+ascii), kept separate from the movement mask so characters never leak in; chat routes purely on isChatPacket with NO follow-up button press (the common sendChat(); sendInput(0) sequence is just an idle release). The server emits exactly one binary message per socket per 24Hz tick = one complete frame: block for one message, apply it, run one perceive->...->resolve cycle, send input only if the mask changed. Frame coalescing (acting only on the freshest queued frame) is a latency optimization NOT a correctness requirement -- a sub-ms step self-corrects. There is no semantic action API: 'do task/kill/vote' are all movement plus A/B at the right place and time. NEGATIVE: mouse messages (0x82/0x83) are NOT read by game logic, so never rely on mouse input; treat the socket closing as episode-over (exit cleanly, do not retry). _{sources: coworlds/coworld-crewrift/README.md, personal_labs/crewrift_lab/crewrift/crewborg/AGENTS.md, personal_labs/crewrift_lab/crewrift/crewborg/design.md, personal_labs/crewrift_lab/docs/crewrift-player.md (+5)}

4. Button input is edge-triggered and 0xFF is a reset hazard; resend-only-on-change is correctness not optimization

crewrift

Crewrift/BitWorld/Persephone all sample RISING-EDGE button presses, not held buttons: a continuously held action bit registers exactly one press then nothing, and re-sending the same mask every tick wastes bandwidth and the server treats a held mask as a held button -- so 'resend only on change' is CORRECTNESS not optimization (it breaks edge-triggered UI like a voting cursor that advances per press). To repeat a one-shot (report/kill/vote-cursor-step/menu nav) release the bit for one tick then re-set it (2-tick minimum cycle); directional movement is exempt (holding continues acceleration). Emit a packet only when the mask changes via one helper (step_button_press(button) returning the button on press and 0 on release, toggling pressed_last_tick) so every task gets release-edge handling free. Treat an all-bits-set mask (0xFF) as a HAZARD: some servers reserve a full mask as a reset/re-register signal, and the high bit (0x80) must never be set -- audit encoding against the server's input handler and mask only intended buttons. Keep the policy's internal action representation separate from the wire and spell out lowering: tasks return an internal ActCommand (buttons + optional chat_text + optional reset_input) and a transport adapter lowers it (one input packet per tick, then at most one chat packet), so tasks never write raw sockets. When a binary/serialized format is in play, treat the producing tool as the byte-layout source of truth and match the parser byte-for-byte (a baker emitted 10-byte edge records: u32 offset, u16 count, u16 src, u16 dst, signed i16 points), validating decoded blobs by byte size and header counts so a version-skewed blob fails loudly. _{sources: claude-code:27659fc3-8e40-469f-beda-31ddd5c6ceca, claude-code:4c297fe5-08a0-4973-85ac-1b8824e638ac, claude-code:cb446cb3-1370-4f0b-9de6-34f05b9e5880, claude-code:ebd6cd36-8956-4a1e-b039-841683ff7792 (+8)}

5. Build the experience-request body against the live schema with the roster field and full slots override

crewrift

Create crewborg/crewrift experience requests via the live route POST /v2/experience-requests (the API was renamed from /v2/episode-requests*; the published CLI ships behind the server and 404s old paths) using coworld.api_client.CoworldApiClient.from_login. Use Bearer auth only (Authorization: Bearer TOKEN), never X-Auth-Token; the token comes from ~/.softmax (softmax.auth.load_current_token / get_api_server) and must not be printed (fetching the Observatory spec unauthenticated returns 403). Always read the live OpenAPI (/openapi.json, schema V2CreateExperienceRequestRequest) before POSTing because the schema drifts (additionalProperties:false; a later drift replaced requester/opponents/rotate_seats with a single roster field of per-seat entries each a policy_ref/top_n/random selector plus a slot pin or -1 for round-robin, and removed backfill while adding a top_n opponent selector); re-check on any 4xx. To force your policy into a role, pin its roster slot AND supply the FULL game_config_overrides.slots array as OBJECTS {"role":"crew"|"imposter", "color"?, "token"?} (one per seat) -- NOT bare role strings (docs showing ["crew","imposter",...] are wrong and yield 400); the override SHALLOW-merges over variant config ({**variant_config, **game_config_overrides}) as whole-key replacements and validates against the GAME's own config_schema (Draft202012Validator), so verify shapes against the coworld manifest schema not the XP-request docs. ownership splits roster control: caller-owned explicit policy_version_ids are owner-gated (a non-owner token cannot pin a specific competitor's policy; competitor control is then only the backfill pool active_high_performers); non-owned tournament opponents go through requester.policy_version_id plus opponents/top_n; the assignments field is valid only with the direct policy_version_ids path. num_episodes 1-100; address policies by Metta policy_version_id UUID or playerName/topN; satisfy requester+opponents+topN == coworld agent count; resolve the canonical coworld version first (one canonical=True row per name) and don't reuse a coworld_id from an old episode tag. _{sources: codex:019e8afb-efcd-7ca0-820f-0320501ef2fa, codex:019e8fc7-ebad-7b00-bc95-df1727641ce0, codex:019e93a0-50c3-71a0-a0dd-c1935af4add0, codex:019e941c-8eb9-7402-a77f-8fe75a5d19bf (+6)}

6. Add a simEvents tooling buffer to crewrift SimServer as runtime-only state, excluded from hash and replay

crewrift · ⚠ session-derived, unverified

When adding a simEvents observation buffer to crewrift's SimServer for tooling, treat it as runtime-only state with hard invariants: it is NOT replay data, NOT game state, NOT included in gameHash, and must NOT influence player observations or policy behavior. Because SimServer is serialized into replay keyframes, clear simEvents at the start of every step (before inputs are applied) AND strip it before keyframe serialization (in serializeReplaySim), or seeking restores stale events from a previous tick. As long as gameHash does not mix in simEvents, the replay file and hash stream stay byte-unchanged. _{sources: codex:019eb8c0-1b42-7a92-843b-c5db259d9ac3, opencode:ses_20af98d9cffeVpWpOGzDAc35WZ}

7. Reset per-meeting scratch on entry, sanitize/rate-limit chat, and delete duplicate state-derivation paths

crewrift · ⚠ session-derived, unverified

Reset all per-meeting scratch (vote confirmed, action queue, vote target, cursor counters, last-LLM-action tick = -1) on mode entry and flush the meeting conversation buffer when leaving the Voting phase so chat context does not leak into the next meeting. Sanitize and rate-limit outbound chat: restrict to printable ASCII, hard-cap length (e.g. 60 chars), enforce a minimum tick gap between chat packets, and store one pending line that the C FFI export drains and the Python policy polls after the step call. Clear per-action working memory on task change so prior-task state can't leak. Do not maintain two parallel paths to derive the same state: when a contract designates a canonical source (e.g. player_knowledge), delete the alternate fallback that rebuilds the same knowledge from belief_state.players, because duplicate reconstruction is a maintenance trap. Check whether a capability already exists on another role's code path before writing new control flow: Crewrift's crewmate report path (body visible + in report range + low velocity -> press A) already existed and the impostor branch just never invoked it, but the impostor branch returned BEFORE the shared holdTaskAction/taskHoldTicks logic so a dedicated impostor-local timer field was the clean fix. _{sources: personal_cogs/among_them/guided_bot/MEETING_DESIGN.md, codex:019e05ef-a042-79c3-aa22-fd78a9e2333d, codex:019e14de-cdca-7482-88fa-81716ee830ae, opencode:ses_21b02c437ffeor4lV5Nb4Cec7y (+2)}