MCP: the agent facade moves into src/agent/, assembled into the development page only

The command tables and the page-side reads, screens and dispatch (scripts/lib/mcp-commands.js and
mcp-page.js) become src/agent/, the facade window.TUBES.call(tool, args) in the page's own scope.
A new <!-- @include-dev agent --> line in src/index.html pastes it in after the game, but only in the
development page (npm run dev, the MCP server, i18n-check, tests that ask with load({agent:true})).
The build drops the line whole: _site/ is byte for byte what main builds.

Tests load the page players get by default, the build test fails if anything outside src/agent/ names
the facade's api/API_ names, and the pages test checks the built page carries none of it and still
plays. ADR 0004 records the rule.
This commit is contained in:
Wolfgang Nagele 2026-11-03 14:51:42 -05:00
parent b2366ed260
commit 5b76685e5c
27 changed files with 1052 additions and 869 deletions

74
tests/agent-api.test.js Normal file
View file

@ -0,0 +1,74 @@
// The agent facade (src/agent/, window.TUBES) and where it lives: in the development page only. It does nothing until
// a tool calls it, listens to toast() only during a call, and the page players get carries none of it.
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { load } = require('./harness');
const page = require('../scripts/lib/page');
// Names the agent files define at the top level: none may appear in the page players get.
const AGENT_NAMES = ['TUBES', 'API_CMD', 'API_DOMAINS', 'apiCall', 'apiDispatch', 'apiSchema'];
test('the facade is inert until called, and listens to the game only during a call', () => {
const a = load({ agent: true });
assert.equal(a.ev('toast.name'), 'toast', 'loading the page leaves toast() alone');
assert.equal(a.ev('spend.name'), 'spend', 'and spend()');
assert.equal(a.ev('API_TOASTS.depth'), 0);
assert.deepEqual(JSON.parse(a.ev('JSON.stringify(TUBES.tools)')).sort(), ['act', 'actions', 'advance', 'catalog', 'city', 'classes', 'click', 'find',
'hot_spots', 'network', 'open_link', 'panel', 'peering_check', 'results', 'schema', 'screen', 'state', 'status', 'traceroute', 'ui'].sort());
// Before a game there is a contract to read, and nothing else.
assert.ok(a.ev("TUBES.call('schema',{section:'commands'}).buildPop"));
assert.throws(() => a.ev("TUBES.call('status',{})"), /No game is running/);
assert.throws(() => a.ev("TUBES.call('eval',{})"), /No tool "eval"/);
a.ev('ACT.start({});S.cash=1e6;compute()');
// A call hears what the game says while it runs, and gives toast() back after, also when it fails.
const r = a.ev("TUBES.call('act',{action:'buyTransit',args:{city:'fra',net:'cog',tier:1}})");
assert.equal(r.outcome, 'applied');
assert.ok(r.toasts.some((t) => /Cogentle/.test(t)), 'the game\'s own words');
assert.equal(a.ev('toast.name'), 'toast');
assert.throws(() => a.ev("TUBES.call('act',{action:'buildPop',args:{city:'atlantis'}})"), /not a cityId/);
assert.equal(a.ev('toast.name+spend.name+API_TOASTS.depth'), 'toastspend0', 'a failing call restores both');
// A toast outside a call is the game's alone.
a.ev("toast('hello','good')");
assert.equal(a.ev('API_TOASTS.list.length'), 0);
assert.deepEqual(a.errors, []);
});
test('the page players get has no agent code; the development page has it', () => {
const ship = page.assemble().html, dev = page.assemble({ dev: true }).html;
assert.ok(!ship.includes('@include-dev'), 'the marker line is dropped whole');
for (const n of AGENT_NAMES) {
assert.ok(!new RegExp(`\\b${n}\\b`).test(ship), `${n} is not in the page players get`);
assert.ok(new RegExp(`\\b${n}\\b`).test(dev), `${n} is in the development page`);
}
// The agent files are pasted in where the marker is, after the game, inside the same script.
const at = dev.indexOf('/* ================= AGENT API: argument domains');
assert.ok(at > dev.indexOf('/* ================= LOOP ================='), 'after the game');
assert.ok(at < dev.lastIndexOf('</script>'), 'inside the game\'s script');
assert.equal(page.shipped().html.match(/\bTUBES\b/), null, 'nor in the shipped page, labels compiled');
// The players' page is the game alone: no facade, and it boots and plays.
const p = load();
assert.equal(p.ev('typeof TUBES+typeof apiCall+typeof API_CMD'), 'undefinedundefinedundefined');
p.ev("ACT.start({});ACT.launchBB({city:'fra'});ACT.buyTransit({city:'fra',net:'cog',tier:1});for(let i=0;i<5;i++)dayTick()");
assert.ok(p.ev('R.served') > 0);
assert.deepEqual(p.errors, []);
});
test('an @include-dev line only expands in the development page', () => {
const src = fs.mkdtempSync(path.join(os.tmpdir(), 'tubes-dev-include-'));
try {
fs.mkdirSync(path.join(src, 'a'));
fs.mkdirSync(path.join(src, 'b'));
fs.writeFileSync(path.join(src, 'a', '10-a.js'), 'const A=1;\n');
fs.writeFileSync(path.join(src, 'b', '10-b.js'), 'const B=2;\n');
fs.writeFileSync(path.join(src, 'index.html'), '<script>\n<!-- @include a -->\n<!-- @include-dev b -->\n</script>\n');
const ship = page.assemble({ src }), dev = page.assemble({ src, dev: true });
assert.equal(ship.html, '<script>\nconst A=1;\n</script>\n');
assert.equal(dev.html, '<script>\nconst A=1;\nconst B=2;\n</script>\n');
// Error lines still map to their files in both.
assert.deepEqual(page.locate(dev.map, 3), { file: 'b/10-b.js', line: 1 });
assert.deepEqual(page.locate(ship.map, 3), { file: 'index.html (shell)', line: 3 });
} finally { fs.rmSync(src, { recursive: true, force: true }); }
});

View file

@ -46,10 +46,28 @@ test('src: partials follow the layout rules (docs/adr/0002-one-page-assembled-at
const src = path.join(root, 'src');
for (const f of listFiles(src)) {
if (f === 'index.html' || f === 'i18n/en.js') continue;
assert.match(f, /^(styles\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.css|game\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.js)$/, `${f}: name it NN-lower-case under styles/ or game/`);
assert.match(f, /^(styles\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.css|(game|agent)\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.js)$/, `${f}: name it NN-lower-case under styles/, game/ or agent/`);
}
for (const dev of [false, true]) {
const { html, map } = assemble({ dev });
assert.equal((html.match(/^const ACT=\{$/gm) || []).length, 1, 'ACT is declared once; other action files use Object.assign(ACT,{…})');
assert.equal((html.match(/<script>/g) || []).length, 2, 'the language loader and the game: one inline game script');
assert.ok(map.length > 50 && map.every((m) => m.to >= m.from), 'the line map covers every partial');
}
});
test('src: the game never names the agent code, which only the development page has (docs/adr/0004-dev-only-code.md)', () => {
// Everything src/agent/ defines at the top level is named api…, API_… (or is window.TUBES), so one pattern finds any
// use of it elsewhere: such code would work in development and break in the page players get.
const { listFiles } = require('../scripts/lib/page');
const src = path.join(root, 'src'), read = (f) => fs.readFileSync(path.join(src, f), 'utf8'), AGENT = /\b(api[A-Z]\w*|API_[A-Z0-9_]+|TUBES)\b/;
let n = 0;
for (const f of listFiles(path.join(src, 'agent'))) {
for (const m of read('agent/' + f).matchAll(/^(?:const|let|var|function|async function)\s+([A-Za-z_$][\w$]*)/gm)) { n++; assert.match(m[1], AGENT, `src/agent/${f}: top-level ${m[1]} is named api… or API_…`); }
}
assert.ok(n > 30, `found the agent's top-level names (${n})`);
for (const f of listFiles(src).filter((f) => !f.startsWith('agent/'))) {
const m = read(f).match(AGENT);
assert.equal(m, null, `src/${f} names ${m && m[0]}, which only the development page defines`);
}
const { html, map } = assemble();
assert.equal((html.match(/^const ACT=\{$/gm) || []).length, 1, 'ACT is declared once; other action files use Object.assign(ACT,{…})');
assert.equal((html.match(/<script>/g) || []).length, 2, 'the language loader and the game: one inline game script');
assert.ok(map.length > 50 && map.every((m) => m.to >= m.from), 'the line map covers every partial');
});

View file

@ -1,17 +1,21 @@
// Loads the game page in jsdom with the animation loop disabled, so tests can drive the simulation
// directly through the game's globals (ACT, S, R, dayTick…). The page is assembled from src/ once per
// test process (scripts/lib/page.js), so tests always run what is in src/, never a stale build.
// It is the page players get; {agent: true} loads the development page instead, with the agent facade
// (src/agent/) the MCP server drives. Only the tests of that facade ask for it, so core code that leans on
// it fails here rather than in production.
const fs = require('node:fs');
const path = require('node:path');
const { JSDOM, VirtualConsole } = require('jsdom');
const { assemble } = require('../scripts/lib/page');
let PAGE = null;
const page = () => PAGE || (PAGE = assemble().html);
const PAGE = {};
const page = (dev) => PAGE[dev] || (PAGE[dev] = assemble({ dev }).html);
// opts.file: a built or older page to load instead (the perf bench, the release build test).
// opts.agent: the development page, with src/agent/.
function load(opts = {}) {
const html = opts.file ? fs.readFileSync(opts.file, 'utf8') : page();
const html = opts.file ? fs.readFileSync(opts.file, 'utf8') : page(!!opts.agent);
const errors = [];
const vc = new VirtualConsole();
vc.on('jsdomError', (e) => {

View file

@ -1,4 +1,4 @@
// The MCP server's act tool (scripts/lib/mcp-commands.js, scripts/lib/mcp-page.js): typed, checked commands with
// The MCP server's act tool (the page's agent facade, src/agent/): typed, checked commands with
// outcomes and quotes, the raw reads (schema, catalog, state, results, ui), and screens beyond the side panel.
const test = require('node:test');
const assert = require('node:assert/strict');
@ -28,7 +28,7 @@ test('every action in the game is in exactly one class, so a new one forces a de
assert.deepEqual(JSON.parse(acts).filter((x) => !all.includes(x)), [], 'every action is classified');
assert.deepEqual(all.filter((x) => !JSON.parse(acts).includes(x)), [], 'every classified action exists');
// Every argument domain resolves, and the tools' fixed vocabularies are the game's.
const bad = ev(`(()=>{const {API_CMD,API_VIEW,API_SESSION,API_DOMAINS,API_TABLES,API_MADE}=window.__mcpCmds,out=[];
const bad = ev(`(()=>{const out=[];
for(const [n,s] of Object.entries({...API_CMD,...API_VIEW,...API_SESSION}))
for(const [nm,d] of (s.args||[])) if(!['string','boolean','integer'].includes(d)&&!API_DOMAINS[d]) out.push(n+'.'+nm+': no domain '+d);
for(const [n,d] of Object.entries(API_DOMAINS)) if(d.table&&!API_TABLES[d.table]&&!(d.table in API_MADE)) out.push('domain '+n+': no table '+d.table);

View file

@ -58,6 +58,20 @@ test('pages: every local file the site refers to is in the build', () => {
for (const m of html.matchAll(/<link[^>]*rel="stylesheet"[^>]*href="(https?:[^"]+)"/g)) assert.match(m[1], /^https:\/\/fonts\.googleapis\.com\//);
});
test('pages: the build carries no agent code, and is the page assembled without it', () => {
// src/agent/ (the facade the MCP server drives) is development-only: one line in src/index.html, expanded by
// the dev server and the MCP server, never by the build (docs/adr/0004-dev-only-code.md).
const html = read('index.html');
assert.doesNotMatch(html, /@include/, 'no include marker survives');
for (const n of ['TUBES', 'API_CMD', 'API_DOMAINS', 'apiCall', 'apiDispatch']) assert.doesNotMatch(html, new RegExp(`\\b${n}\\b`), `${n} is not shipped`);
const { load } = require('./harness');
const { ev, errors } = load({ file: path.join(OUT, 'index.html') });
assert.equal(ev('typeof TUBES'), 'undefined');
ev("ACT.start({});ACT.launchBB({city:'fra'});for(let i=0;i<10;i++)dayTick()");
assert.ok(ev('S.day') >= 10);
assert.deepEqual(errors, []);
});
test('pages: only the release workflow deploys, and only with the GitHub Pages actions', () => {
const dir = path.join(root, '.github', 'workflows');
for (const f of fs.readdirSync(dir)) {