docs(plans): Add design spec for a bot/agent API

[sebyx07]

• Relates to Expose a bot/agent API for Zero Hour, in the spirit of BWAPI #3328

AI disclosure (AI_POLICY.md §2): the research, the spec files and this description were drafted with Claude (Claude Code) and posted at my direction. I reviewed the content and am accountable for it; review questions will be answered by me. This PR contains no code — only a design spec, so the design can be agreed before anything is implemented.

TL;DR

• A spec only for the bot/agent API proposed in Expose a bot/agent API for Zero Hour, in the spirit of BWAPI #3328 — no engine changes.
• It answers the points @xezon and @bobtista raised in Expose a bot/agent API for Zero Hour, in the spirit of BWAPI #3328; overview.md has a table mapping each point to where it is answered.
• Shape: an off-by-default bridge in Core/; the bot runs out of process (any language) over loopback TCP (Windows, Linux native/Wine, macOS via Wine); orders go only through the existing GameMessage path after UI-parity checks; observation is fog-respecting by default; SDKs / Gym env / MCP server / referee live in a separate repo.
• What I'm asking for now: answers to the open questions at the bottom of overview.md. A plan is much cheaper to change than code.

Full description

All files are under docs/plans/2026/09/21/101-bot-agent-api/. Every file:line reference was checked against main @ 241f01926.

File	Content
overview.md	TL;DR, maintainer-feedback map, architecture, stages, done-when, risks, open questions
00-prior-art.md	BWAPI (internals, flags, TournamentModule, competition rules), SC2 API, 0 A.D. RL interface, Spring, Gym/µRTS/Lux, NewShoes (an existing agent bridge for the ZH WebAssembly port), Pluto, Jev, LLM-in-RTS work — with the lesson each gives
01-engine-seams.md	Where commands, the frame loop, validation, fog, headless, CRC and match setup live today; getters an observer must never call (Object::getShroudedStatus, getDelayBetweenShots, createGroup, …); platform status
02-observation.md	Stage 1: read-only snapshot at the end of GameLogic::update (so it also works in headless replay); player / camera / full visibility modes; records, feature planes and entity arrays for ML
03-commands-and-hardening.md	Stage 2: orders expanded into select + order GameMessages, injected after propagateMessages(); client-side UI-parity checks (e.g. no attacking shrouded targets); action masks; optional logic-side hardening behind RETAIL_COMPATIBLE_CRC
04-bridge-protocol.md	Transport, JSON + binary framing, handshake, batch observe / act, realtime vs step timing — including what happens when a bot stalls
05-match-setup-and-lobby.md	Skirmish and LAN host/join through the same code paths as the menus; two people each running their own bot on their own machine; human + AI co-pilot; [BOT] tag in the player name
06-headless-and-step.md	Headless live matches, uncapped speed, step mode, one port per instance, multi-instance
07-sdk-gym-mcp.md	External repo: SDKs, Gymnasium/PettingZoo, a fast-decision (Jev) harness, an MCP server, and recipes for models that know nothing about C&C
08-referee-and-tournament.md	External repo: referee proxy, time budgets, capability veto, match runner
09-verification.md	Replay round-trip in the existing replay CI job, observer purity, fog-leak and UI-parity tests, cross-platform matrix

Key decisions (all open to change)

• Bots are indistinguishable from players at the engine boundary. Orders are ordinary GameMessages for the local player, so replays, CRC and network sync are unchanged.
• One bot per game process. Bot vs bot means one instance per bot, not several bots inside one engine — this avoids the multi-local-player changes @bobtista mentioned.
• The game never waits in realtime mode. Step mode, where the game waits for the bot, only runs in skirmish/headless and never in network games.
• full visibility is refused in network games.

About the plan layout

The directory follows the planning layout we use at developerz-ai for AI-assisted work (dated dir, overview.md + one slice per area, status.yml as the only tracker, file:line references instead of pasted code): https://github.com/developerz-ai/gold-standards-in-ai. If the project prefers a different place or shape — the wiki, a Discussion, or only the external repo — I'll move it.

🤖 Generated with Claude Code

[coderabbitai]

Understand this PR’s impact

Explore downstream dependencies and potential security impact with Blast Radius.

View blast radius →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ea62ca16-d1cb-4638-8818-0a5d1e6ded71

📥 Commits

Reviewing files that changed from the base of the PR and between d78f4d3 and b45baa1.

📒 Files selected for processing (4)

• docs/plans/2026/09/21/101-bot-agent-api/04-bridge-protocol.md
• docs/plans/2026/09/21/101-bot-agent-api/05-match-setup-and-lobby.md
• docs/plans/2026/09/21/101-bot-agent-api/07-sdk-gym-mcp.md
• docs/plans/2026/09/21/101-bot-agent-api/08-referee-and-tournament.md

🚧 Files skipped from review as they are similar to previous changes (4)

• docs/plans/2026/09/21/101-bot-agent-api/08-referee-and-tournament.md
• docs/plans/2026/09/21/101-bot-agent-api/07-sdk-gym-mcp.md
• docs/plans/2026/09/21/101-bot-agent-api/04-bridge-protocol.md
• docs/plans/2026/09/21/101-bot-agent-api/05-match-setup-and-lobby.md

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

Walkthrough

The pull request adds a staged design for a disabled-by-default Zero Hour Bot/Agent API. It defines engine seams, fog-safe observations, validated commands, bridge transport, match setup, headless execution, SDK integrations, referee controls, and verification.

Changes

Bot Agent API

Layer / File(s)	Summary
Architecture and engine foundation docs/plans/2026/09/21/101-bot-agent-api/overview.md, docs/plans/2026/09/21/101-bot-agent-api/00-prior-art.md, docs/plans/2026/09/21/101-bot-agent-api/01-engine-seams.md	The plan defines the API architecture, prior-art findings, engine command flow, visibility constraints, replay behavior, timing, and platform limits.
Observation, commands, and bridge protocol docs/plans/2026/09/21/101-bot-agent-api/02-observation.md, docs/plans/2026/09/21/101-bot-agent-api/03-commands-and-hardening.md, docs/plans/2026/09/21/101-bot-agent-api/04-bridge-protocol.md	The design specifies snapshots, fog modes, opaque identifiers, validated GameMessage orders, action results, authenticated transport, batch requests, timing modes, and safety limits.
Match operation and agent integrations docs/plans/2026/09/21/101-bot-agent-api/05-match-setup-and-lobby.md, docs/plans/2026/09/21/101-bot-agent-api/06-headless-and-step.md, docs/plans/2026/09/21/101-bot-agent-api/07-sdk-gym-mcp.md, docs/plans/2026/09/21/101-bot-agent-api/08-referee-and-tournament.md	The plans define lobby and team scenarios, bot disclosure, headless and deterministic step execution, SDK/Gymnasium/MCP interfaces, and referee-managed matches.
Verification and plan status docs/plans/2026/09/21/101-bot-agent-api/09-verification.md, docs/plans/2026/09/21/101-bot-agent-api/status.yml	The verification checklist covers replay, CRC, fog, authentication, transport, seat scoping, order parity, and step determinism. The status manifest records ownership, progress, evidence, and update state.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains that the pull request adds a design-only bot/agent API specification and summarizes its scope.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a design specification for a bot/agent API.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

The documentation-only PR appears safe to merge, with no outstanding previous findings or newly identified actionable defects.

Summary

This PR adds a design specification for an opt-in, out-of-process bot/agent API that observes game state, submits commands through existing GameMessage paths, supports realtime and step-based operation, and delegates SDK, training, and tournament tooling to an external repository. The changes since the previous review further clarify credential delivery and the security boundary.

• Defines fog-aware observation modes, command validation, protocol framing, and engine integration points.
• Describes lobby automation, headless execution, SDK/Gym/MCP layers, referee isolation, and verification requirements.
• Keeps the bridge disabled by default and restricts multiplayer visibility and seat control.
• Replaces command-line/file-based token delivery with an inherited channel and explicitly requires OS-user or sandbox isolation for untrusted bots.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Bot[Bot or agent] --> SDK[External SDK / Gym / MCP]
    SDK --> Referee[Optional referee proxy]
    Referee -->|Authenticated loopback protocol| Bridge[Engine bot bridge]
    Bridge --> Observe[Fog-aware snapshot writer]
    Bridge --> Validate[UI-parity validation]
    Validate --> Messages[GameMessage command path]
    Messages --> Logic[Game logic / network / replay]
    Logic --> Observe

Loading

_{Reviews (3) · Last reviewed commit: "docs(plans): Address review: token chann..."}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: af90624e-333d-49f1-891c-6e38fc914e1d

📥 Commits

Reviewing files that changed from the base of the PR and between 241f019 and d78f4d3.

📒 Files selected for processing (12)

• docs/plans/2026/09/21/101-bot-agent-api/00-prior-art.md
• docs/plans/2026/09/21/101-bot-agent-api/01-engine-seams.md
• docs/plans/2026/09/21/101-bot-agent-api/02-observation.md
• docs/plans/2026/09/21/101-bot-agent-api/03-commands-and-hardening.md
• docs/plans/2026/09/21/101-bot-agent-api/04-bridge-protocol.md
• docs/plans/2026/09/21/101-bot-agent-api/05-match-setup-and-lobby.md
• docs/plans/2026/09/21/101-bot-agent-api/06-headless-and-step.md
• docs/plans/2026/09/21/101-bot-agent-api/07-sdk-gym-mcp.md
• docs/plans/2026/09/21/101-bot-agent-api/08-referee-and-tournament.md
• docs/plans/2026/09/21/101-bot-agent-api/09-verification.md
• docs/plans/2026/09/21/101-bot-agent-api/overview.md
• docs/plans/2026/09/21/101-bot-agent-api/status.yml

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[Skyaero42]

We don't add these types of plans to the code. If you want to discuss these type of plans it is best to open a discussion. Definitive plans can be added by editing the main issue post (e.g. with a checklist).

Be aware that at the moment we do not implement large features. We are still mainly working on bugs, performance, code optimization and modernization and it is unlikely that the feature will be worked on any time in the near future. Additionally, as some mentioned in the related issue, there are a lot of pre-conditions that need to be checked and worked on before such an API can be provide.

Last, I would like to say that AI is notoriously bad in writing good feature and user stories unless explicitly guided and prompted. The docs added in this PR are difficult to read for a human. They are summarizations of an explorative AI.

Closing this PR as this type of information does not belong in the code repository.

[xezon]

Yes lets not add these plans to the repository. Seems unnecessary.