From 7438fd106562506f5e6ab774d9d04905c5cd4d58 Mon Sep 17 00:00:00 2001 From: Wolfgang Nagele Date: Tue, 3 Nov 2026 15:30:04 -0500 Subject: [PATCH] Agent mode: an AI agent plays in the player's own tab, with the agent's clock or a running one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The MCP server gains a second session, --browser: the game in the player's tab, reached through the agent relay npm run dev hosts at /agent (loopback unless --host; Host and Origin checked, no token). The player turns it on in Settings → Agent API, a section only the development page has, and picks the clock: a pace of 30 s to 5 min a day that nobody can pause, or the agent's own. Headless gets the running clock too (--clock realtime --pace MS) and both get a wait tool. All of it lives in src/agent/ (development page only). The game offers HOOKS, UI.clockLocked, setSpeed() and runClock(dt), the frame's day block moved out unchanged, and nothing more: the page players get grows by under 1 KB gzipped and runs exactly as before. --- .claude/skills/edit-the-game/SKILL.md | 5 +- CHANGELOG.md | 1 + CLAUDE.md | 2 +- README.md | 4 +- docs/ARCHITECTURE.md | 9 +- docs/MCP.md | 135 +++-- package-lock.json | 3 +- package.json | 6 +- scripts/agent/relay.js | 113 +++++ scripts/dev.js | 32 +- scripts/lib/mcp-browser.js | 64 +++ scripts/lib/mcp-game.js | 144 ++++-- scripts/lib/mcp-headless.js | 4 +- scripts/lib/relay-client.js | 72 +++ scripts/mcp.js | 95 +++- site/i18n/de.js | 11 + site/i18n/es.js | 11 + site/i18n/fr.js | 11 + site/i18n/it.js | 11 + site/i18n/pt.js | 11 + src/agent/10-domains.js | 7 +- src/agent/20-commands.js | 8 +- src/agent/30-docs.js | 9 + src/agent/40-read.js | 21 +- src/agent/50-screen.js | 27 +- src/agent/60-dispatch.js | 18 +- src/agent/70-time.js | 39 +- src/agent/75-mode.js | 86 ++++ src/agent/80-relay.js | 77 +++ src/agent/85-ticker.js | 24 + src/agent/90-facade.js | 25 +- src/agent/99-start.js | 4 + src/game/50-state.js | 6 +- src/game/60-features/20-scenarios.js | 2 +- src/game/60-features/92-puzzles.js | 2 +- src/game/90-actions/10-interface.js | 6 +- src/game/90-actions/89-game-and-settings.js | 2 +- src/game/90-actions/91-slots.js | 2 +- src/game/91-save.js | 3 +- src/game/93-ui/20-phone.js | 3 +- src/game/93-ui/40-hud-and-panels.js | 3 +- src/game/95-modals/30-modal-and-names.js | 4 +- src/game/96-map/30-settings.js | 8 +- src/game/96-map/90-input.js | 2 +- src/game/99-loop.js | 15 +- src/i18n/en.js | 11 + tests/agent-api.test.js | 22 +- tests/agent-relay.test.js | 528 ++++++++++++++++++++ tests/agent-settings.test.js | 166 ++++++ tests/harness.js | 5 +- tests/mcp-commands.test.js | 2 +- tests/mcp-parity.test.js | 83 +++ tests/mcp.test.js | 33 ++ 53 files changed, 1827 insertions(+), 170 deletions(-) create mode 100644 scripts/agent/relay.js create mode 100644 scripts/lib/mcp-browser.js create mode 100644 scripts/lib/relay-client.js create mode 100644 src/agent/75-mode.js create mode 100644 src/agent/80-relay.js create mode 100644 src/agent/85-ticker.js create mode 100644 src/agent/99-start.js create mode 100644 tests/agent-relay.test.js create mode 100644 tests/agent-settings.test.js create mode 100644 tests/mcp-parity.test.js diff --git a/.claude/skills/edit-the-game/SKILL.md b/.claude/skills/edit-the-game/SKILL.md index db249cb..aca2564 100644 --- a/.claude/skills/edit-the-game/SKILL.md +++ b/.claude/skills/edit-the-game/SKILL.md @@ -56,7 +56,10 @@ next to it. `npm run page -- -o /tmp/page.html` writes the page players get if y development page only (``): players never download it. Its top-level names start with `api`/`API_`, and **nothing in `src/game/` may name them**: that would work in `npm run dev` and break for players (`tests/build.test.js` checks). Tests load the players' page; a test of the - facade asks for `load({ agent: true })`. See docs/adr/0004-dev-only-code.md. + facade asks for `load({ agent: true })`. Where agent code must change what the game does (agent mode + locks the clock, adds a Settings section and a HUD badge), the game calls `HOOKS.x?.()` and reads + `UI.clockLocked` (`50-state.js`), and agent code fills them in: add a hook there rather than an `if` for + the agent in a game file. See docs/adr/0004-dev-only-code.md. - **Panels and modals:** `93-ui/` (HUD, side panels), `94-dashboard/` (NOC dashboard, bank), `95-modals/`. - **Styles:** the matching `src/styles/*.css`; phone rules go in `60-phone.css`. - **Data tables** (cities, cables, networks): one entry per line, and keep id-keyed objects such as diff --git a/CHANGELOG.md b/CHANGELOG.md index fbebed3..8b4e731 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project are documented here. The project follows ## [Unreleased] +- If you run the game on your own computer, an AI agent can now play it in your browser while you watch. Turn the Agent API on in Settings (the section only appears in a copy of the game you run with npm run dev, never on seriesoftub.es) and point an AI client at the game's MCP server: every move happens live on your screen, and docs/MCP.md in the repository explains the setup. You choose the clock: a pace from one simulated day every 30 seconds to 5 minutes, which nobody can pause and which waits while no agent is connected, or the agent moves time itself. Your game, your settings and the windows you open stay yours. - Every capital in Africa is on the map, which puts every capital of the world in the game: 33 new cities from Porto-Novo, Bamako and Niamey to Khartoum, Juba, Mogadishu, Brazzaville, Tripoli, Rabat and Pretoria. Each country brings its real telcos, Nigeria gets its wholesale backbone up to Abuja, and the island capitals of the Comoros, São Tomé and Equatorial Guinea sit on their real cables. - Every capital in South, East and Southeast Asia and the Pacific is on the map: Thimphu, Kathmandu, Bandar Seri Begawan, Phnom Penh, Vientiane, Ulaanbaatar, Naypyidaw, Pyongyang, Dili, Hanoi and Wellington, with the island capitals Tarawa, Palikir, Yaren, Funafuti and Port Vila. Each country brings its real telcos, North Korea reaches the world only through China and Russia, and the islands hang on their real cables. - Every capital in the Middle East, the Caucasus and Central Asia is on the map, from Yerevan and Baku to Kabul, Tehran, Baghdad, Jerusalem, Amman, Kuwait City, Beirut, Damascus, Sanaa and Manama, with Ankara and Islamabad. Each country brings its real telcos, and Bahrain is an island on the Gulf's cables. diff --git a/CLAUDE.md b/CLAUDE.md index 093e7d0..439c4a1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,7 @@ Read these before larger changes: ```bash npm ci # once: installs jsdom for the tests -npm run dev # play while developing: http://localhost:8080, reloads on save +npm run dev # play while developing: http://localhost:8080, reloads on save (--host to share) npm test # node:test + jsdom, every tests/*.test.js, must stay green node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken" (and sorted dictionaries) node scripts/i18n-add.js FILE.json # add/change/remove translations (see `add-strings`) diff --git a/README.md b/README.md index 58aec61..ec085fa 100644 --- a/README.md +++ b/README.md @@ -52,11 +52,11 @@ and remembers the one you pick under Settings or on the title screen. ```sh npm ci -npm run dev # development server: assembles src/ on every request, reloads on save +npm run dev # development server on localhost (--host to share): assembles src/ on every request, reloads on save npm test # headless tests: boot, geography, a year of play, every incident, every panel npm run build # writes the site for GitHub Pages to _site/, with version and date stamped in npm run i18n:check # lists text missing from (or stale in) the translations -npm run mcp # the game as an MCP server, so an AI client can play and debug it (docs/MCP.md; --http for HTTP) +npm run mcp # the game as an MCP server, so an AI client can play and debug it, headless or in your tab (docs/MCP.md) ``` ## Community diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a7f010e..75127a5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -49,7 +49,9 @@ hoisted across files, and top-level statements run in path order. Find code by n `src/agent/` is the agent facade (`window.TUBES`): the typed commands, reads and screens the MCP server plays through. It is assembled into the **development page** only (`npm run dev`, the MCP server, tests that ask for it); the page players get never has it ([ADR 0004](adr/0004-dev-only-code.md)). Its top-level names all start with -`api`/`API_`, and nothing outside `src/agent/` may use them. +`api`/`API_`, and nothing outside `src/agent/` may use them. Where it must reach into the game (agent mode in the +player's tab locks the clock and draws its badge and Settings section), the game offers `HOOKS` and the flag +`UI.clockLocked` (`50-state.js`), empty and false in the page players get, and `runClock(dt)` (`99-loop.js`). Rules for the source (checked by `tests/build.test.js` and the assembler): files are named `NN-lower-case.js`/`.css`, end with a newline and never close their `