From 62c242c9a73913675c22b30356684d9041e796d9 Mon Sep 17 00:00:00 2001 From: Christopher Hawker Date: Tue, 3 Nov 2026 22:54:54 +1100 Subject: [PATCH 01/12] The intern can keep PNI and IX ports ahead of their traffic (closes #234) A new standing order, Keep peering headroom, works like the transit one: it keeps each PNI and IX port above a multiple of today's traffic (1.25x to 3x). A single port at a POP with several routers gets a second port in a LAG; any other port moves up to the smallest port size that fits, or the biggest the router takes. If the preferred move cannot be done it tries the other one. It pays through the same actions as a click (ACT.pni, ACT.lagP, ACT.buyIx, ACT.lagIx), is off by default, has the Headroom and Budget dials and the per-POP switch, and keeps to the cash floor. A PNI augment on order is waited for, router ports an augment will take are not promised twice, and nothing is bought while a DDoS flood is live, since the flood counts as port usage. The intern's monthly bill figure (opsMoNow) now counts IX ports too. --- CHANGELOG.md | 1 + site/i18n/de.js | 3 + site/i18n/es.js | 3 + site/i18n/fr.js | 3 + site/i18n/it.js | 3 + site/i18n/pt.js | 3 + src/game/60-features/95-standing-orders.js | 28 +++- src/i18n/en.js | 3 + tests/intern-ports.test.js | 181 +++++++++++++++++++++ 9 files changed, 226 insertions(+), 2 deletions(-) create mode 100644 tests/intern-ports.test.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 5882c7c..1f51ed2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project are documented here. The project follows ## [Unreleased] +- The NOC intern has a new order, Keep peering headroom, that adds capacity to your PNI and IX ports before they fill up (#234). A single port at a POP with several routers gets a second port in a LAG, so no router is its only way out; any other port moves up to the smallest port size that fits. It has the same Headroom and Budget dials as the transit order, can be switched off per POP, waits out a DDoS flood instead of buying ports for it, and a PNI with an augment already on order waits for it to land. The monthly figure in the intern's log now counts IX ports too. - You can pay to hurry the survey, permits and factory of your own subsea cable, 30 days at a time (#258). Money only goes so far: the cable still has to be made, about two months plus a day for every 80 km, before the lay ships sail. - Three new cities in northern Australia: Port Hedland, Townsville and Alice Springs (#255). Port Hedland lands a new cable up the coast to Darwin and a branch of Darwin's cable out to Singapore; Alice Springs has no sea at all. In the wet season, November to April, fiber cuts in the tropical north, Darwin included, take twice as long to reach. - Traceroute no longer shows an "embedded cache in your rack" hop on paths that leave over transit, an exchange or a PNI. Only traffic that really ends at one of your cache boxes shows it now. diff --git a/site/i18n/de.js b/site/i18n/de.js index 74030ff..055543e 100644 --- a/site/i18n/de.js +++ b/site/i18n/de.js @@ -2894,6 +2894,7 @@ "ops.l_paid":"Kosten: {cost} einmalig, {mo}/Monat.", "ops.l_peer":{"one":"hat mit einem Netz an {where} gepeert","other":"hat mit {n} Netzen an {where} gepeert"}, "ops.l_pni":{"one":"hat einen PNI in {where} bestellt","other":"hat {n} PNIs bestellt ({where})"}, +"ops.l_ports":{"one":"hat einen Peering-Port in {where} aufgestockt","other":"hat {n}-mal Peering-Ports aufgestockt ({where})"}, "ops.l_quiet":"{name} hat auf die Graphen geschaut. Nichts zu tun.", "ops.l_repair":{"one":"hat eine Reparatur beschleunigt","other":"hat {n} Reparaturen beschleunigt"}, "ops.l_routers":{"one":"hat Router in {where} aufgerüstet","other":"hat Router an {n} Orten aufgerüstet ({where})"}, @@ -2926,6 +2927,8 @@ "ops.o_optics_d":"Optiken auf heiß laufende Dark Fiber stecken und neue Glasfaser am Tag der Übergabe beleuchten.", "ops.o_pni":"PNI mit den Großen", "ops.o_pni_d":"Jede Woche: mit jedem willigen Netz, das an deinen POPs genug Traffic schickt, einen PNI bestellen, in der jeweils kleinsten Größe des Netzes.", +"ops.o_ports":"Peering-Reserve halten", +"ops.o_ports_d":"PNI- und IX-Ports über einem Vielfachen des heutigen Traffics halten: ein einzelner Port an einem POP mit mehreren Routern bekommt einen zweiten im LAG, alle anderen eine Portgröße hoch.", "ops.o_repair":"Reparaturen beschleunigen", "ops.o_repair_d":"Für jeden Ausfall mit Eil-Reparatur zahlen, solange das Budget reicht.", "ops.o_routers":"Router voraus halten", diff --git a/site/i18n/es.js b/site/i18n/es.js index af82c14..446471c 100644 --- a/site/i18n/es.js +++ b/site/i18n/es.js @@ -2892,6 +2892,7 @@ "ops.l_paid":"Coste: {cost} de entrada, {mo}/mes.", "ops.l_peer":{"one":"hizo peering con una red en {where}","other":"hizo peering con {n} redes en {where}"}, "ops.l_pni":{"one":"pidió un PNI en {where}","other":"pidió {n} PNIs ({where})"}, +"ops.l_ports":{"one":"amplió un puerto de peering en {where}","other":"amplió puertos de peering {n} veces ({where})"}, "ops.l_quiet":"{name} miró las gráficas. No había nada que hacer.", "ops.l_repair":{"one":"aceleró una reparación","other":"aceleró {n} reparaciones"}, "ops.l_routers":{"one":"mejoró los routers en {where}","other":"mejoró los routers en {n} sitios ({where})"}, @@ -2924,6 +2925,8 @@ "ops.o_optics_d":"Añadir ópticas a la fibra oscura que va caliente y encender la fibra nueva el día que te la entregan.", "ops.o_pni":"PNI con los grandes", "ops.o_pni_d":"Cada semana: pedir un PNI a cada red dispuesta que envíe suficiente tráfico en tus POPs, con el tamaño mínimo de cada red.", +"ops.o_ports":"Margen en puertos de peering", +"ops.o_ports_d":"Mantener los puertos PNI e IX por encima de un múltiplo del tráfico de hoy: un puerto único en un POP con varios routers recibe un segundo en LAG, todos los demás suben un tamaño de puerto.", "ops.o_repair":"Acelerar reparaciones", "ops.o_repair_d":"Pagar la reparación urgente de cada caída que la tenga, mientras dure el presupuesto.", "ops.o_routers":"Routers por delante", diff --git a/site/i18n/fr.js b/site/i18n/fr.js index f49e497..53a2731 100644 --- a/site/i18n/fr.js +++ b/site/i18n/fr.js @@ -2892,6 +2892,7 @@ "ops.l_paid":"Coût : {cost} d'entrée, {mo}/mois.", "ops.l_peer":{"one":"a peeré avec un réseau à {where}","other":"a peeré avec {n} réseaux à {where}"}, "ops.l_pni":{"one":"a commandé un PNI à {where}","other":"a commandé {n} PNI ({where})"}, +"ops.l_ports":{"one":"a renforcé un port de peering à {where}","other":"a renforcé des ports de peering {n} fois ({where})"}, "ops.l_quiet":"{name} a surveillé les graphes. Rien à faire.", "ops.l_repair":{"one":"a accéléré une réparation","other":"a accéléré {n} réparations"}, "ops.l_routers":{"one":"a mis à niveau les routeurs à {where}","other":"a mis à niveau les routeurs à {n} endroits ({where})"}, @@ -2924,6 +2925,8 @@ "ops.o_optics_d":"Ajouter des optiques sur la fibre noire qui chauffe, et allumer la nouvelle fibre le jour de sa livraison.", "ops.o_pni":"PNI avec les gros", "ops.o_pni_d":"Chaque semaine : commander un PNI avec chaque réseau partant qui envoie assez de trafic sur tes POP, à la taille minimale de chaque réseau.", +"ops.o_ports":"Garder de la marge sur les ports de peering", +"ops.o_ports_d":"Garder les ports PNI et IX au-dessus d'un multiple du trafic du jour : un port unique dans un POP à plusieurs routeurs en reçoit un deuxième en LAG, tous les autres passent à une taille de port au-dessus.", "ops.o_repair":"Accélérer les réparations", "ops.o_repair_d":"Payer la réparation express de chaque panne qui en a une, tant que le budget suit.", "ops.o_routers":"Garder les routeurs en avance", diff --git a/site/i18n/it.js b/site/i18n/it.js index 1a4e781..31727d0 100644 --- a/site/i18n/it.js +++ b/site/i18n/it.js @@ -2892,6 +2892,7 @@ "ops.l_paid":"Costo: {cost} subito, {mo}/mese.", "ops.l_peer":{"one":"ha fatto peering con una rete a {where}","other":"ha fatto peering con {n} reti a {where}"}, "ops.l_pni":{"one":"ha ordinato un PNI a {where}","other":"ha ordinato {n} PNI ({where})"}, +"ops.l_ports":{"one":"ha aumentato una porta di peering a {where}","other":"ha aumentato le porte di peering {n} volte ({where})"}, "ops.l_quiet":"{name} ha guardato i grafici. Niente da fare.", "ops.l_repair":{"one":"ha accelerato una riparazione","other":"ha accelerato {n} riparazioni"}, "ops.l_routers":{"one":"ha potenziato i router a {where}","other":"ha potenziato i router in {n} posti ({where})"}, @@ -2924,6 +2925,8 @@ "ops.o_optics_d":"Aggiungi ottiche alla dark fiber che scotta e accendi la fibra nuova il giorno della consegna.", "ops.o_pni":"PNI con i grandi", "ops.o_pni_d":"Ogni settimana: ordina un PNI con ogni rete disponibile che manda abbastanza traffico nei tuoi POP, alla taglia minima di ciascuna rete.", +"ops.o_ports":"Margine sulle porte di peering", +"ops.o_ports_d":"Tieni le porte PNI e IX sopra un multiplo del traffico di oggi: una porta singola in un POP con più router ne riceve una seconda in LAG, tutte le altre passano a una porta più grande.", "ops.o_repair":"Accelera le riparazioni", "ops.o_repair_d":"Paga la riparazione urgente di ogni guasto che ce l'ha, finché il budget regge.", "ops.o_routers":"Router sempre avanti", diff --git a/site/i18n/pt.js b/site/i18n/pt.js index 131881a..c0c8c63 100644 --- a/site/i18n/pt.js +++ b/site/i18n/pt.js @@ -2892,6 +2892,7 @@ "ops.l_paid":"Custo: {cost} de entrada, {mo}/mês.", "ops.l_peer":{"one":"fez peering com uma rede em {where}","other":"fez peering com {n} redes em {where}"}, "ops.l_pni":{"one":"pediu um PNI em {where}","other":"pediu {n} PNIs ({where})"}, +"ops.l_ports":{"one":"reforçou uma porta de peering em {where}","other":"reforçou portas de peering {n} vezes ({where})"}, "ops.l_quiet":"{name} ficou olhando os gráficos. Nada a fazer.", "ops.l_repair":{"one":"acelerou um reparo","other":"acelerou {n} reparos"}, "ops.l_routers":{"one":"melhorou os roteadores em {where}","other":"melhorou os roteadores em {n} lugares ({where})"}, @@ -2924,6 +2925,8 @@ "ops.o_optics_d":"Adicionar ópticas à fibra escura que está esquentando e acender a fibra nova no dia da entrega.", "ops.o_pni":"PNI com os grandes", "ops.o_pni_d":"Toda semana: pedir um PNI com cada rede disposta que mande tráfego suficiente nos seus POPs, no tamanho mínimo de cada rede.", +"ops.o_ports":"Folga nas portas de peering", +"ops.o_ports_d":"Manter as portas PNI e IX acima de um múltiplo do tráfego de hoje: uma porta única num POP com vários roteadores ganha uma segunda em LAG, todas as outras sobem um tamanho de porta.", "ops.o_repair":"Acelerar reparos", "ops.o_repair_d":"Pagar o reparo urgente de cada queda que tenha um, enquanto o orçamento durar.", "ops.o_routers":"Roteadores à frente", diff --git a/src/game/60-features/95-standing-orders.js b/src/game/60-features/95-standing-orders.js index 15f0e70..2bf7dbf 100644 --- a/src/game/60-features/95-standing-orders.js +++ b/src/game/60-features/95-standing-orders.js @@ -12,6 +12,7 @@ const INTERNS={ // fees, or (mo) of the running costs the order adds, for caches, which are free to rack but cost rent every month. const OPS=[ {k:'transit',i:'📈',pop:1,cap:50000,t:N_('ops.o_transit'),d:N_('ops.o_transit_d'),p:{x:{d:1.5,v:[1.25,1.5,2,3],l:N_('ops.p_x'),f:v=>v+'×'},prov:{d:'cheap',ok:v=>v==='cheap'||v==='have'||(isNet(v)&&!!NET[v].price),l:N_('ops.p_prov')}}}, + {k:'ports',i:'🔌',pop:1,cap:50000,t:N_('ops.o_ports'),d:N_('ops.o_ports_d'),p:{x:{d:1.5,v:[1.25,1.5,2,3],l:N_('ops.p_x'),f:v=>v+'×'}}}, {k:'routers',i:'🧠',pop:1,cap:250000,t:N_('ops.o_routers'),d:N_('ops.o_routers_d'),p:{at:{d:80,v:[60,70,80,90],l:N_('ops.p_at'),f:v=>v+'%'},how:{d:'auto',v:['auto','add','swap'],l:N_('ops.p_how'),f:v=>tr({auto:N_('ops.how_auto'),add:N_('ops.how_add'),swap:N_('ops.how_swap')}[v])}}}, {k:'caches',i:'📦',pop:1,cap:5000,mo:1,t:N_('ops.o_caches'),d:N_('ops.o_caches_d'),p:{g:{d:5,v:[1,5,10,25,50],l:N_('ops.p_g'),f:v=>fmtG(v)}}}, {k:'ix',i:'🔀',t:N_('ops.o_ix'),d:N_('ops.o_ix_d'),p:{}}, @@ -24,7 +25,7 @@ const OPS=[ const OPSK=Object.fromEntries(OPS.map(o=>[o.k,o])),OPS_POP=OPS.filter(o=>o.pop).map(o=>o.k); const OPS_TPL=['bb','transit','ix','kit']; // What the shift log can say. One line per day: "{name} did this, that and the other." -const OPS_SAY={transit:N_('ops.l_transit'),routers:N_('ops.l_routers'),caches:N_('ops.l_caches'),rs:N_('ops.l_rs'),peer:N_('ops.l_peer'),pni:N_('ops.l_pni'),sales:N_('ops.l_sales'),decline:N_('ops.l_decline'),repair:N_('ops.l_repair'),optics:N_('ops.l_optics'),decom:N_('ops.l_decom'),broke:N_('ops.l_broke'),snag:N_('ops.l_snag')}; +const OPS_SAY={transit:N_('ops.l_transit'),ports:N_('ops.l_ports'),routers:N_('ops.l_routers'),caches:N_('ops.l_caches'),rs:N_('ops.l_rs'),peer:N_('ops.l_peer'),pni:N_('ops.l_pni'),sales:N_('ops.l_sales'),decline:N_('ops.l_decline'),repair:N_('ops.l_repair'),optics:N_('ops.l_optics'),decom:N_('ops.l_decom'),broke:N_('ops.l_broke'),snag:N_('ops.l_snag')}; // Fat fingers: rare, visible, harmless. Only the LAG one costs anything, and only a little. const OPS_FF=[N_('ops.ff_desc'),N_('ops.ff_hostname'),N_('ops.ff_typo'),N_('ops.ff_lag'),N_('ops.ff_ping')]; const OPS_TRIALS=1,OPS_FF_RATE={oncall:1/150,bgp:1/60}; @@ -90,6 +91,7 @@ function opsMoNow(){let m=cachesMo(); for(const l of S.links)m+=(l.mo||0)+(l.kind==='df'?(l.spares?Math.round(150+(l.ch||[]).length*80):0)+(l.regen|0)*REGEN_MO:0); for(const t of S.transit)m+=transitMo(t,0); for(const p of S.pni){const q=p.up||p,N=NET[p.net];m+=(q.g1?Math.round(PORT[0].pni/2):PORT[q.tier].pni)*(q.n||1)+(N.pol==='paid'&&!paidFree(N)?N.paidFee:0);} + for(const c in S.ixp)if(!S.myIx[c])m+=ixPortMo(c,S.ixp[c])*((S.ixn||{})[c]||1); return m;} const opsFFLine=e=>tr('ops.ff_line',{name:tr(INTERNS[e.i].s),what:tr(OPS_FF[e.f],{city:CITY[e.c].name})}); // Mute what a click would show (toasts, sounds, floaters, the full redraw) and keep the player's selection. @@ -154,6 +156,28 @@ const OPS_RUN={ if(i!==undefined)job={cost:PORT[i].setup,go:()=>ACT.buyTransit({city:c,net:n.id,tier:i}),w:'+'+PORT[i].n};}} if(!job||!X.can('transit',job.cost)||!X.pay('transit',job.go))break; X.did('transit',c+' '+job.w);ts=S.transit.filter(t=>t.city===c);}}}, + // PNIs and IX ports keep Headroom times today's traffic, hottest first. One port at a POP with several routers gets a + // second in a LAG, so it is not the only way out; anything else moves up to the smallest port size that fits. A PNI + // augment lands weeks later, so that port waits for it. A flood fills ports for a day or two: not worth buying for. + ports(X){if(ddosAll().length)return;const N=opsP('ports','x'),L=[], + // Router ports that pending PNI augments will take when they land are spoken for. + resv=c=>S.pni.reduce((a,p)=>p.up&&p.city===c?a+Math.max(0,PORT_SLOT(p.up.tier)*(p.up.n||1)-PORT_SLOT(p.tier)*(p.n||1)):a,0),room=c=>portsMax(c)-portsUsed(c)+1e-9-resv(c); + // Each port: cap() now, use today, lag() and ups() the jobs it could have as {cost, cap after, w for the log, go}, sig() to see a job took. + for(const p of S.pni){const c=p.city,use=R.usePni[p.id]||0,cap=()=>lagCap(pniG(p),p.n),n=()=>p.n||1;if(!pniOn(p)||p.up||!(use>0)||cap()>=N*use||!opsHere('ports',c))continue; + L.push({city:c,use,u:use/cap(),cap,n,rt:(S.pops[c]||{}).routers||1,busy:()=>!!p.up,sig:()=>[p.tier,n(),!!p.g1,!!p.up].join(), + lag:()=>n()ACT.lagP({id:p.id,d:1})}:null, + ups:()=>{const out=[];for(let t=p.g1?0:p.tier+1;tACT.pni({city:c,net:p.net,tier:t})});}return out;}});} + for(const x in S.ixp){const c=ixCity(x),use=R.useIx[x]||0,cap=()=>ixCap(x),n=()=>(S.ixn||{})[x]||1,pop=S.pops[c];if(S.myIx[x]||!(use>0)||!(cap()>0)||cap()>=N*use||!opsHere('ports',c))continue; + const g=()=>PORT[S.ixp[x]].g; + L.push({city:c,use,u:use/cap(),cap,n,rt:pop?pop.routers||1:1,busy:()=>false,sig:()=>S.ixp[x]+','+n(), + lag:()=>pop&&n()ACT.lagIx({city:x,d:1})}:null, + // A remote port (no POP there) stops at 100G; at a POP the router has to take the bigger port. + ups:()=>{const out=[],t0=S.ixp[x];for(let t=t0+1;troom(c):t>1)continue; + out.push({cost:ixPortMo(x,t)*n(),cap:cap()*lagCap(PORT[t].g,n())/lagCap(g(),n()),w:PORT[t0].n+'→'+PORT[t].n,go:()=>ACT.buyIx({city:x,tier:t})});}return out;}});} + for(const o of L.sort((a,b)=>b.u-a.u))for(let step=0;step<3&&!o.busy()&&o.cap()u.cap>=N*o.use)||ups.at(-1),job=o.n()<2&&o.rt>1?lag||fit:fit||lag,was=o.sig(); + if(!job||!X.can('ports',job.cost)||!X.pay('ports',()=>{job.go();return o.sig()!==was;}))break; + X.did('ports',o.city+' '+job.w);}}, optics(X){const at=opsP('optics','at')/100,big=opsP('optics','pick')==='big',gpd=(o,l)=>optG(o,l)/optCost(o); for(const l of S.links){if(l.kind!=='df'||l.ready>S.day||l.eqDown>S.day||l.standby||l.cut>S.day)continue; let cap=dfCap(l);const load=(R.load&&R.load[l.id])||0; @@ -197,7 +221,7 @@ const OPS_RUN={ function opsDecomSafe(l){const bz=S.biz.filter(b=>(b.reqs||[]).some(k=>k==='diverse'||k==='sharks'||k==='lat')&&b.city2);if(!bz.length)return true; const chk=b=>(b.reqs||[]).every(k=>k==='diverse'?diversePaths(b.city,b.city2):k==='sharks'?terrestrialPath(b.city,b.city2):k==='lat'?bestLat(b.city,b.city2)<=b.latMax:true); const was=bz.filter(chk),all=S.links;S.links=all.filter(x=>x!==l);try{return was.every(chk);}finally{S.links=all;}} -const OPS_ORDER=['repair','sales','routers','transit','optics','caches','ix','pni','decom']; +const OPS_ORDER=['repair','sales','routers','transit','ports','optics','caches','ix','pni','decom']; // The shift: once per game day from dayTick, after outages and events have had their turn. function opsDay(d){if(!opsHired())return;const O=S.ops,m=monthIdx(d);if(m!==O.mon){O.mon=m;for(const k in O.spent)O.spent[k]=0;O.addMo={};} // A new week: last week's tally becomes the shift report, and the one NOC notice of the week. diff --git a/src/i18n/en.js b/src/i18n/en.js index 51d1f2f..a1d5e60 100644 --- a/src/i18n/en.js +++ b/src/i18n/en.js @@ -2893,6 +2893,7 @@ "ops.l_paid":"Cost: {cost} up front, {mo}/mo.", "ops.l_peer":{"one":"peered with a network at {where}","other":"peered with {n} networks at {where}"}, "ops.l_pni":{"one":"ordered a PNI in {where}","other":"ordered {n} PNIs ({where})"}, +"ops.l_ports":{"one":"topped up a peering port in {where}","other":"topped up peering ports {n} times ({where})"}, "ops.l_quiet":"{name} watched the graphs. Nothing needed doing.", "ops.l_repair":{"one":"rushed a repair","other":"rushed {n} repairs"}, "ops.l_routers":{"one":"upgraded routers in {where}","other":"upgraded routers in {n} places ({where})"}, @@ -2925,6 +2926,8 @@ "ops.o_optics_d":"Add optics to dark fiber that runs hot, and light new fiber the day it is handed over.", "ops.o_pni":"PNI with the big ones", "ops.o_pni_d":"Every week: order a PNI with every willing network sending enough traffic at your POPs, at each network's own minimum size.", +"ops.o_ports":"Keep peering headroom", +"ops.o_ports_d":"Keep PNI and IX ports above a multiple of today's traffic: a single port at a POP with several routers gets a second one in a LAG, anything else moves up a port size.", "ops.o_repair":"Rush repairs", "ops.o_repair_d":"Pay for the rush repair on every outage that has one, while the budget lasts.", "ops.o_routers":"Keep routers ahead", diff --git a/tests/intern-ports.test.js b/tests/intern-ports.test.js new file mode 100644 index 0000000..d0129eb --- /dev/null +++ b/tests/intern-ports.test.js @@ -0,0 +1,181 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { load } = require('./harness'); + +// The intern's "Keep peering headroom" order: PNI and IX ports above a multiple of today's traffic. One port at a POP with +// several routers gets a second in a LAG; anything else moves up a port size. Same setup as the other standing-order tests: +// a small network, a hired intern, no cash floor, no fat fingers (Change Freeze). +const BASE = "ACT.start({});S.cash=1e8;for(const g of GOALS)S.done[g.id]=0;S.lvl=3;S.nextFail=S.nextEvent=1e9;UI.speed=0;S.rules=makeRules('freeze');" + + "ACT.launchBB({city:'fra'});S.pops.fra.bb.d=300;S.pops.fra.rgen=1;ACT.buyTransit({city:'fra',net:'cog',tier:1});compute()"; +function game(t, extra = '') { + const h = load(); + t.after(() => h.dom.window.close()); + h.ev(BASE); + if (extra) h.ev(extra); + return h; +} +const hire = ev => ev("ACT.opsHire({id:'kevin'});S.ops.floor=0;closeModal()"); +// Hiring recomputes, which would wipe the traffic a case stages: hire first, then stage. +function hired(t, extra) { const h = game(t); hire(h.ev); h.ev(extra); return h; } +const on = (ev, p = { x: 1.5 }, cap) => ev(`S.ops.on.ports=true;S.ops.p.ports=${JSON.stringify(p)};${cap === undefined ? '' : `S.ops.cap.ports=${cap};`}`); +const shift = ev => ev('opsDay(S.day)'); +const cash = ev => ev('S.cash'); +// A 10G PNI with a small network at Frankfurt, carrying `use` Gbps today. PNIs are up the moment they are ordered, so the +// outcome does not wait on a lead time. +const pni = (tier, use, n = 1) => `S.rules.pnis='instant';S.pni.push({id:'p1',city:'fra',net:'drz',tier:${tier},n:${n},ready:0});compute();R.usePni.p1=${use}`; +const ix = (tier, use) => `S.rules.pnis='instant';ACT.buyIx({city:'fra',tier:${tier},signed:true});compute();R.useIx.fra=${use}`; +const PNIS = "JSON.stringify(S.pni.map(p=>[p.net,p.tier,p.n||1,!!p.up]))"; +const IXP = "JSON.stringify([S.ixp.fra,(S.ixn||{}).fra||1])"; +// The same game twice: the intern's shift in one, the player's own clicks in the other. Both must cost the same and end the same. +function twins(t, extra, manual, pick, x = 1.5) { + const A = game(t), B = game(t); + hire(A.ev); hire(B.ev); + A.ev(extra); B.ev(extra); + on(A.ev, { x }); + const a0 = cash(A.ev); shift(A.ev); const a1 = cash(A.ev); + const b0 = cash(B.ev); B.ev(manual); const b1 = cash(B.ev); + assert.ok(a0 - a1 > 0, 'the order did some paid work'); + assert.equal(a0 - a1, b0 - b1, 'the shift cost exactly what the clicks cost'); + assert.equal(A.ev(pick), B.ev(pick), 'and left the network the same'); + assert.deepEqual(A.errors, []); assert.deepEqual(B.errors, []); + return A; +} + +test('a hot PNI at a one-router POP moves up a port size, exactly as the click would', t => { + const A = twins(t, pni(0, 9), "ACT.pni({city:'fra',net:'drz',tier:1})", PNIS); + assert.equal(A.ev('S.pni[0].tier'), 1); + assert.equal(A.ev('S.pni[0].n||1'), 1, 'one port, not a LAG'); + assert.match(A.ev('opsEntry(S.ops.log[0])'), /Kevin topped up a peering port in Frankfurt 10G→100G/); +}); + +test('a single PNI port at a POP with several routers gets a second port in a LAG', t => { + const A = twins(t, pni(0, 9) + ";S.pops.fra.routers=2;compute();R.usePni.p1=9", "ACT.lagP({id:'p1',d:1})", PNIS); + assert.equal(A.ev('S.pni[0].tier'), 0, 'same size'); + assert.equal(A.ev('S.pni[0].n'), 2); + assert.match(A.ev('opsEntry(S.ops.log[0])'), /Kevin topped up a peering port in Frankfurt \+1×10G/); +}); + +test('a PNI that is already a LAG moves up a port size, whatever the routers', t => { + const A = twins(t, pni(0, 15, 2) + ";S.pops.fra.routers=2;compute();R.usePni.p1=15", "ACT.pni({city:'fra',net:'drz',tier:1})", PNIS); + assert.equal(A.ev('S.pni[0].tier'), 1); + assert.equal(A.ev('S.pni[0].n'), 2, 'the LAG keeps its members'); +}); + +test('the same two rules for an IX port', t => { + const up = twins(t, ix(0, 9), "ACT.buyIx({city:'fra',tier:1})", IXP); + assert.equal(up.ev(IXP), '[1,1]', 'one router: a bigger port'); + assert.match(up.ev('opsEntry(S.ops.log[0])'), /topped up a peering port in Frankfurt 10G→100G/); + const lag = twins(t, ix(0, 9) + ";S.pops.fra.routers=2;compute();R.useIx.fra=9", "ACT.lagIx({city:'fra',d:1})", IXP); + assert.equal(lag.ev(IXP), '[0,2]', 'several routers: a second port in a LAG'); + const big = twins(t, ix(0, 15) + ";S.ixn={fra:2};S.pops.fra.routers=2;compute();R.useIx.fra=15", "ACT.buyIx({city:'fra',tier:1})", IXP); + assert.equal(big.ev(IXP), '[1,2]', 'a LAG moves up as a whole'); +}); + +test('it picks the smallest port that gives the headroom, and the biggest the router takes when none does', t => { + // 120G of traffic at 1.5× needs 180G: 100G is too small, 400G fits. + const A = twins(t, pni(1, 99) + ";R.usePni.p1=99", "ACT.pni({city:'fra',net:'drz',tier:2})", PNIS); + assert.equal(A.ev('S.pni[0].tier'), 2); + // A router that tops out at 100G cannot take a bigger port: another member of the LAG instead. + const B = twins(t, "S.pops.fra.rgen=0;" + pni(1, 95), "ACT.lagP({id:'p1',d:1})", PNIS); + assert.equal(B.ev('S.pni[0].tier'), 1); + assert.equal(B.ev('S.pni[0].n'), 2); + // 380G of traffic at 3× needs 1140G: the next size up (800G) is still too small, so it skips to 1.6T in one order. + const C = twins(t, "S.pops.fra.rgen=3;" + pni(2, 380), "ACT.pni({city:'fra',net:'drz',tier:4})", PNIS, 3); + assert.equal(C.ev('S.pni[0].tier'), 4); +}); + +test('it leaves ports with their headroom alone, and does nothing when switched off', t => { + const { ev, errors } = hired(t, pni(1, 20) + ";" + ix(0, 5)); + on(ev); + const s0 = ev(`${PNIS}+${IXP}`), c0 = cash(ev); + shift(ev); + assert.equal(ev(`${PNIS}+${IXP}`), s0); + assert.equal(cash(ev), c0); + assert.equal(ev('S.ops.log[0].r.length'), 0, 'a quiet shift'); + ev('R.usePni.p1=95;R.useIx.fra=9;S.ops.on.ports=false'); + shift(ev); + assert.equal(cash(ev), c0, 'off: hot ports stay as they are'); + assert.deepEqual(errors, []); +}); + +test('a PNI augment on order is waited for, not ordered twice', t => { + const { ev, errors } = hired(t, "S.rules.pnis='wait';S.pni.push({id:'p1',city:'fra',net:'drz',tier:0,ready:0});compute();R.usePni.p1=9"); + on(ev); + shift(ev); + assert.equal(ev('S.pni[0].up&&S.pni[0].up.tier'), 1, 'the augment is ordered'); + assert.equal(ev('S.pni[0].tier'), 0, 'and lands later'); + const c1 = cash(ev), up = ev('JSON.stringify(S.pni[0].up)'); + ev('R.usePni.p1=9'); shift(ev); + assert.equal(cash(ev), c1, 'a second shift buys nothing'); + assert.equal(ev('JSON.stringify(S.pni[0].up)'), up); + assert.deepEqual(errors, []); +}); + +test('the router ports an augment on order will take are not promised twice', t => { + // A hot 100G PNI, a hot 10G PNI and a hot IX port, two routers, one free port: the hottest gets its second member and nobody else can have a port. + const { ev, errors } = hired(t, "S.rules.pnis='wait';S.pops.fra.routers=2;S.transit.push({id:'fill',city:'fra',net:'ntt',tier:1,n:43,down:0},{id:'fill2',city:'fra',net:'ntt',tier:0,n:6,down:0});ACT.buyIx({city:'fra',tier:0,signed:true});" + + "S.pni.push({id:'p1',city:'fra',net:'drz',tier:1,ready:0},{id:'p2',city:'fra',net:'vdp',tier:0,ready:0});compute();R.usePni.p1=95;R.usePni.p2=9;R.useIx.fra=9"); + on(ev); + assert.equal(ev("portsMax('fra')-portsUsed('fra')"), 1); + shift(ev); + assert.equal(ev('S.pni[0].up&&S.pni[0].up.n'), 2, 'the hotter PNI is the one that gets the port'); + assert.ok(!ev('S.pni[1].up'), 'the 10G one gets neither a member nor a bigger port'); + assert.equal(ev(IXP), '[0,1]', 'and neither does the exchange port'); + assert.ok(ev("portsUsed('fra')+S.pni.reduce((a,p)=>a+(p.up?Math.max(0,PORT_SLOT(p.up.tier)*(p.up.n||1)-PORT_SLOT(p.tier)*(p.n||1)):0),0)") <= ev("portsMax('fra')"), 'and the POP is not over-booked'); + assert.deepEqual(errors, []); +}); + +test('it keeps to the monthly budget, the cash floor and the per-POP switch', t => { + const { ev, errors } = hired(t, pni(0, 9)); + on(ev, { x: 1.5 }, 10000); + ev('S.ops.spent.ports=9000'); + shift(ev); + assert.equal(ev('S.pni[0].tier'), 0, 'over the budget: left alone'); + assert.match(ev('opsEntry(S.ops.log[0])'), /stopped at the budget for Keep peering headroom/); + ev('S.ops.spent.ports=0;S.ops.floor=1e8'); + ev('R.usePni.p1=9'); shift(ev); + assert.equal(ev('S.pni[0].tier'), 0, 'under the cash floor: left alone'); + ev("S.ops.floor=0;ACT.opsPop({k:'ports',city:'fra'});closeModal();R.usePni.p1=9"); + shift(ev); + assert.equal(ev('S.pni[0].tier'), 0, 'switched off at this POP'); + ev("ACT.opsPop({k:'ports',city:'fra'});closeModal();R.usePni.p1=9"); + shift(ev); + assert.equal(ev('S.pni[0].tier'), 1, 'and on again'); + assert.deepEqual(errors, []); +}); + +test('it waits out a flood instead of buying ports for it', t => { + const { ev, errors } = hired(t, pni(0, 9)); + on(ev); + ev("S.ev.ddos={id:'a',city:'fra',tgt:'bb:fra',vec:'http',gbps:20,start:S.day,until:S.day+3};compute();R.usePni.p1=9"); + const c0 = cash(ev); + shift(ev); + assert.equal(cash(ev), c0); + assert.equal(ev('S.pni[0].tier'), 0); + ev("S.ev.ddos=null;compute();R.usePni.p1=9"); shift(ev); + assert.equal(ev('S.pni[0].tier'), 1, 'the day after, it gets on with it'); + assert.deepEqual(errors, []); +}); + +test('the monthly bill the intern reports includes IX ports', t => { + const { ev, errors } = hired(t, ix(0, 9)); + on(ev); + const m0 = ev('opsMoNow()'); + shift(ev); + assert.equal(ev('S.ixp.fra'), 1); + assert.equal(ev('opsMoNow()') - m0, ev('ixPortMo("fra",1)-ixPortMo("fra",0)')); + assert.equal(ev('S.ops.log[0].mo'), ev('opsMoNow()') - m0, 'and the log says so'); + assert.deepEqual(errors, []); +}); + +test('an old save has the order off, and a new save keeps its dials', t => { + const { ev, errors } = game(t); + hire(ev); on(ev, { x: 2 }, 250000); + ev("S.ops.skip.fra=['ports'];save();S=migrate(JSON.parse(slotRaw(UI.slot)))"); + assert.equal(ev("S.ops.on.ports&&S.ops.p.ports.x===2&&S.ops.cap.ports===250000&&S.ops.skip.fra[0]==='ports'"), true); + ev("delete S.ops.on.ports;delete S.ops.p.ports;delete S.ops.cap.ports;delete S.ops.spent.ports;S=migrate(JSON.parse(JSON.stringify(S)))"); + assert.equal(ev('S.ops.on.ports'), false, 'an intern hired before the order existed does not start doing it'); + assert.equal(ev('opsP("ports","x")'), 1.5); + assert.equal(ev('S.ops.spent.ports'), 0); + assert.deepEqual(errors, []); +}); From 5b76685e5c838447fbaf723bfa21efd769208a83 Mon Sep 17 00:00:00 2001 From: Wolfgang Nagele Date: Tue, 3 Nov 2026 14:51:42 -0500 Subject: [PATCH 02/12] 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 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. --- .claude/skills/edit-the-game/SKILL.md | 14 +- .claude/skills/write-tests/SKILL.md | 3 +- CLAUDE.md | 3 +- docs/ARCHITECTURE.md | 19 +- docs/MCP.md | 14 +- docs/adr/0004-dev-only-code.md | 46 ++ scripts/dev.js | 5 +- scripts/i18n-check.js | 3 +- scripts/lib/fuzz-page.js | 2 +- scripts/lib/mcp-game.js | 85 +-- scripts/lib/mcp-headless.js | 34 ++ scripts/lib/mcp-page.js | 487 ------------------ scripts/lib/page.js | 18 +- src/agent/10-domains.js | 104 ++++ .../agent/20-commands.js | 332 +----------- src/agent/30-docs.js | 145 ++++++ src/agent/40-read.js | 217 ++++++++ src/agent/50-screen.js | 64 +++ src/agent/60-dispatch.js | 114 ++++ src/agent/70-time.js | 38 ++ src/agent/90-facade.js | 43 ++ src/index.html | 1 + tests/agent-api.test.js | 74 +++ tests/build.test.js | 28 +- tests/harness.js | 10 +- tests/mcp-commands.test.js | 4 +- tests/pages.test.js | 14 + 27 files changed, 1052 insertions(+), 869 deletions(-) create mode 100644 docs/adr/0004-dev-only-code.md create mode 100644 scripts/lib/mcp-headless.js delete mode 100644 scripts/lib/mcp-page.js create mode 100644 src/agent/10-domains.js rename scripts/lib/mcp-commands.js => src/agent/20-commands.js (66%) create mode 100644 src/agent/30-docs.js create mode 100644 src/agent/40-read.js create mode 100644 src/agent/50-screen.js create mode 100644 src/agent/60-dispatch.js create mode 100644 src/agent/70-time.js create mode 100644 src/agent/90-facade.js create mode 100644 tests/agent-api.test.js diff --git a/.claude/skills/edit-the-game/SKILL.md b/.claude/skills/edit-the-game/SKILL.md index 7dc75dd..db249cb 100644 --- a/.claude/skills/edit-the-game/SKILL.md +++ b/.claude/skills/edit-the-game/SKILL.md @@ -14,6 +14,7 @@ load, so splitting code across files costs nothing at runtime. Why it works this src/index.html the shell: , static markup, ``, `` src/styles/NN-*.css CSS, in order (phones last) src/game/NN-area/NN-*.js the game script, in order (see the map in docs/ARCHITECTURE.md) +src/agent/NN-*.js the agent facade the MCP server drives: in the development page only site/ static files copied as they are (dictionaries, icons, service worker) ``` @@ -34,7 +35,8 @@ npm test -- tests/peering.test.js # one suite ``` A browser error points at a line of the assembled page; the dev server prints the `src/` file and line -next to it. `npm run page -- -o /tmp/page.html` writes the assembled page if you want to look at it. +next to it. `npm run page -- -o /tmp/page.html` writes the page players get if you want to look at it; +`npm run page -- --source --dev -o /tmp/page.html` the development page `npm run dev` serves. ## Where new code goes @@ -48,9 +50,13 @@ next to it. `npm run page -- -o /tmp/page.html` writes the assembled page if you - **Actions:** add `name:(args)=>{…},` to the matching `src/game/90-actions/*.js`. Only `10-interface.js` declares `const ACT={`; the others are `Object.assign(ACT,{ … });`. A new area can get a new `NN-area.js` file of that second form. The MCP server types every action: a new one also gets - an entry in `scripts/lib/mcp-commands.js` (a game command with its argument domains, a view, a draft - or a session action) or in the server's `DENY` list in `scripts/lib/mcp-page.js`; - `tests/mcp-commands.test.js` fails until it has one. + an entry in `src/agent/20-commands.js` (a game command with its argument domains, a view, a draft, + a session action, or `API_DENY`); `tests/mcp-commands.test.js` fails until it has one. +- **Agent code** (`src/agent/`, the facade the MCP server plays through) is assembled into the + 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. - **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/.claude/skills/write-tests/SKILL.md b/.claude/skills/write-tests/SKILL.md index efe406c..42937b9 100644 --- a/.claude/skills/write-tests/SKILL.md +++ b/.claude/skills/write-tests/SKILL.md @@ -7,7 +7,8 @@ description: Write deterministic jsdom tests for Series of Tubes features and fi Tests use `node:test` and `tests/harness.js`, which assembles the game page from `src/` (once per test file) and loads it in jsdom with the animation loop off, a seeded `Math.random` and a recording fake canvas. -Code runs inside the page through `ev()`. +Code runs inside the page through `ev()`. `load()` is the page players get; tests of the agent facade +(`src/agent/`, `window.TUBES`) ask for the development page with `load({ agent: true })`. ## Pattern diff --git a/CLAUDE.md b/CLAUDE.md index e383fa1..ac8bdd0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,8 @@ https://seriesoftub.es, hosted on GitHub Pages. The game is one static page with Its source is many small files in `src/` (`src/styles/*.css`, `src/game/**/*.js`, the shell `src/index.html`); the build pastes them together, in path order, into a single `index.html`, the same one-file page players have always loaded. Static files (dictionaries, icons, service worker) -live in `site/`. +live in `site/`. `src/agent/` (the facade the MCP server plays through) goes into the development page only, +never into the page players get, and nothing in `src/game/` may use it (`docs/adr/0004-dev-only-code.md`). Read these before larger changes: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9729449..e8bd6f5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -11,8 +11,10 @@ src/ the game page, in pieces i18n/en.js the English for every label → inlined at the top of the page's `; return html.replace('', `${hint}${RELOAD}`); diff --git a/scripts/i18n-check.js b/scripts/i18n-check.js index 8d8e657..fd21bb2 100644 --- a/scripts/i18n-check.js +++ b/scripts/i18n-check.js @@ -16,7 +16,8 @@ const D = require('./lib/dict'); const { CALL } = require('./legacy/labels'); const SITE = path.join(__dirname, '..', 'site'); -const page = () => require('./lib/page').assemble().html; +// The development page: it has every label, the agent's (src/agent/) too. +const page = () => require('./lib/page').assemble({ dev: true }).html; const LABEL = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/; // The labels the game uses, with problems in how they are used. diff --git a/scripts/lib/fuzz-page.js b/scripts/lib/fuzz-page.js index 4586d55..d2a6f35 100644 --- a/scripts/lib/fuzz-page.js +++ b/scripts/lib/fuzz-page.js @@ -1,4 +1,4 @@ -// Runs inside a game page (scripts/route-fuzz.js loads two: main's and this checkout's), next to scripts/lib/mcp-page.js. +// Runs inside a game page (scripts/route-fuzz.js loads two: main's and this checkout's). // The driver picks every move with its own seeded random numbers and sends the same calls to both pages, so the pages // stay in lockstep; this file only offers what a player could do now (buttons on screen, POPs, cities) and digests what // routing gave, as strings the driver compares. diff --git a/scripts/lib/mcp-game.js b/scripts/lib/mcp-game.js index fbf0983..1b357ac 100644 --- a/scripts/lib/mcp-game.js +++ b/scripts/lib/mcp-game.js @@ -1,12 +1,14 @@ -// The game behind the MCP server (scripts/mcp.js): one game page from src/, loaded in jsdom like the tests load it -// (tests/harness.js: seeded, no animation loop), with scripts/lib/mcp-commands.js (the typed command tables) and -// scripts/lib/mcp-page.js added to read and drive it. TOOLS is the list the server offers; each run() gets the -// session and the tool's arguments and returns JSON. +// The game behind the MCP server (scripts/mcp.js): one game page of its own, the development page from src/ (with the +// agent facade, src/agent/), loaded in jsdom as the tests load it (tests/harness.js: seeded, no animation loop), with +// scripts/lib/mcp-headless.js added to start, load and export games. Every other tool is the page's own facade +// (TUBES.call), so the server plays the game the way the page itself would be played. +// +// TOOLS is the list the server offers; each run() gets the session and the tool's arguments and returns JSON. const fs = require('node:fs'); const path = require('node:path'); const { load } = require('../../tests/harness'); -const PAGE_JS = ['mcp-commands.js', 'mcp-page.js'].map((f) => fs.readFileSync(path.join(__dirname, f), 'utf8')); +const HEADLESS_JS = fs.readFileSync(path.join(__dirname, 'mcp-headless.js'), 'utf8'); const ACT_DIR = path.join(__dirname, '..', '..', 'src', 'game', '90-actions'); // The arguments of the actions the command tables do not type (the drafts), read from their source @@ -24,23 +26,30 @@ function actArgs() { } const MAX_INLINE_SAVE = 200000; +// One call into a jsdom page's facade, as JSON both ways: nothing but plain data crosses. +function pageCall(g, tool, args = {}) { + const w = g.dom.window; + w.__mcpTool = tool; w.__mcpArgs = JSON.parse(JSON.stringify(args)); + return JSON.parse(g.ev('JSON.stringify(TUBES.call(__mcpTool,__mcpArgs))') || 'null'); +} + +// opts.seed, opts.file as tests/harness.js takes them (a file must be a development page: it carries the facade). function createSession(opts = {}) { let game = null; const boot = () => { - const g = load({ seed: opts.seed || 12345, file: opts.file }); - for (const js of PAGE_JS) g.ev(js); - g.call = (fn, ...args) => { - g.dom.window.__mcpArgs = JSON.parse(JSON.stringify(args)); - return JSON.parse(g.ev(`JSON.stringify(__mcp.${fn}(...window.__mcpArgs))`) || 'null'); - }; - g.call('newGame', { city: 'fra', name: 'Scratch Networks', preset: 'oncall' }); + const g = load({ seed: opts.seed || 12345, file: opts.file, agent: true }); + g.ev(HEADLESS_JS); + g.headless = (fn, ...args) => { g.dom.window.__mcpArgs = JSON.parse(JSON.stringify(args)); return JSON.parse(g.ev(`JSON.stringify(__mcpHeadless.${fn}(...window.__mcpArgs))`) || 'null'); }; + g.headless('newGame', { city: 'fra', name: 'Scratch Networks', preset: 'oncall' }); return g; }; const session = { get game() { return game || (game = boot()); }, - call(fn, ...args) { return session.game.call(fn, ...args); }, + // The page's own tools (TUBES.call). + call(name, args) { return pageCall(session.game, name, args); }, + headless(fn, ...args) { return session.game.headless(fn, ...args); }, // Text into the page without building a giant eval string (saves run to megabytes). - loadSave(txt) { session.game.dom.window.__mcpSave = txt; return JSON.parse(session.game.ev('JSON.stringify(__mcp.loadSave(window.__mcpSave))')); }, + loadSave(txt) { session.game.dom.window.__mcpSave = txt; return JSON.parse(session.game.ev('JSON.stringify(__mcpHeadless.loadSave(window.__mcpSave))')); }, errors() { return game ? game.errors.slice() : []; }, }; return session; @@ -52,6 +61,8 @@ const bool = (description) => ({ type: 'boolean', description }); const obj = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false }); const SECTIONS = ['clock', 'commands', 'view', 'session', 'drafts', 'denied', 'domains', 'state', 'results']; const WHERE = ['modal', 'bank', 'dash', 'panel', 'left', 'puzzle']; +// A page tool, passed straight through: the MCP tool's arguments are the facade's. +const page = (name) => (s, a) => s.call(name, a); const TOOLS = [ { @@ -60,7 +71,7 @@ const TOOLS = [ inputSchema: obj({ city: str('Home city: id (fra) or name (Frankfurt). Default Frankfurt.'), name: str('Network name (24 characters at most). Default: a random pun.'), preset: str('Rules preset', { enum: ['soft', 'freeze', 'oncall', 'bgp', 'sandbox'] }), seed: num('Random seed, default 12345.'), asn: num('Your own AS number, as the title screen takes it. Default: a free one.'), chaos: str('Sandbox only: how often things break. Default none.', { enum: ['none', 'calm', 'normal', 'spicy'] }) }), - run: (s, a) => s.call('newGame', a), + run: (s, a) => s.headless('newGame', a), }, { name: 'load_save', @@ -77,7 +88,7 @@ const TOOLS = [ description: 'Export the current game as a save file the real game can import (Menu → Import save). Writes it to path, or returns it when it is small.', inputSchema: obj({ path: str('Where to write the .json file.') }), run: (s, a) => { - const txt = s.call('exportSave', require('../../package.json').version); + const txt = s.headless('exportSave', require('../../package.json').version); if (a.path) { fs.writeFileSync(path.resolve(a.path), txt); return { wrote: path.resolve(a.path), bytes: Buffer.byteLength(txt) }; } if (txt.length > MAX_INLINE_SAVE) throw new Error(`The save is ${txt.length} characters; give a path to write it to.`); return JSON.parse(txt); @@ -87,86 +98,86 @@ const TOOLS = [ name: 'status', description: 'The network at a glance: date, cash, monthly revenue and costs by kind, level, tier and why it is not Tier 1 yet, the current goal, traffic, reach, counts, POPs and open incidents.', inputSchema: obj(), - run: (s) => s.call('status'), + run: page('status'), }, { name: 'advance', description: 'Run the game forward day by day, as the game loop does. Stops early when a window opens (then read it with screen and answer it with click or act; decision says when it is a question with options) or the network goes bankrupt. Returns what happened: log, toasts, new incidents, cash, and how long each simulated day took.', inputSchema: obj({ days: num('Days to run, 1 to 3650. Default 1.') }), - run: (s, a) => s.call('advance', a.days), + run: page('advance'), }, { name: 'network', description: 'Everything about one network (a carrier, eyeball network, CDN…): type, peering policy and what it asks for, traffic share, transit price, PoPs, exchanges, upstreams and customer cone, whether Tier 1 needs it, and for you: demand, how its traffic leaves you (egress by kind), your PNIs and sessions with it, and how to move it to peering.', inputSchema: obj({ network: str('Id (dtk), name (Doitsche Telekomm) or ASN.') }, ['network']), - run: (s, a) => s.call('network', a.network), + run: page('network'), }, { name: 'city', description: 'One city: country, exchanges and their member counts, data center, who sells transit there and at what price, the networks present, the cables that land there, and your POP if you have one.', inputSchema: obj({ city: str('Id (fra) or name (Frankfurt).') }, ['city']), - run: (s, a) => s.call('city', a.city), + run: page('city'), }, { name: 'find', description: 'Search cities, networks, cables and exchanges by name, id or ASN. Use it to get the ids other tools and actions take.', inputSchema: obj({ query: str('Part of a name, an id or an ASN.'), kind: str('Only this kind', { enum: ['city', 'network', 'cable', 'exchange'] }) }, ['query']), - run: (s, a) => s.call('find', a.query, a.kind), + run: page('find'), }, { name: 'traceroute', description: 'The game\'s looking glass: the path traffic takes from one of your POPs to a network (which exit wins and why, with the AS path) or to another of your POPs (prefix it city:).', inputSchema: obj({ from: str('One of your POPs: id or name.'), to: str('A network (id, name or ASN), or city:.') }, ['from', 'to']), - run: (s, a) => s.call('trace', a.from, a.to), + run: page('traceroute'), }, { name: 'peering_check', description: 'Would this network peer with you, and if not, why not? Checks a PNI at each of your POPs where it is, and a session at each exchange you are on where it is a member, with the game\'s own reasons (traffic it wants, paid peering, the Tier 1 club…).', inputSchema: obj({ network: str('Id, name or ASN.'), city: str('Only this city.'), via: str('Only this way', { enum: ['pni', 'ix'] }) }, ['network']), - run: (s, a) => s.call('peering', a.network, a.city, a.via), + run: page('peering_check'), }, { name: 'hot_spots', description: 'Where it hurts: the fullest links, transit ports and PNIs, the transit bill by carrier, and the networks with the most traffic still over transit, each with the cheapest way to peer with it.', inputSchema: obj({ limit: num('How many of each, default 10.') }), - run: (s, a) => s.call('hotSpots', a.limit || 10), + run: page('hot_spots'), }, { name: 'schema', description: 'The typed contract act checks against: every game command with its arguments, their domains and a description, which ones dry-run, decide or confirm; view commands; session actions (scenarios, puzzles, runs); drafts (inputs another command reads); what is not available and why; the argument domains; and a field-by-field reference of state and results. Give section for one part.', inputSchema: obj({ section: str('One part only', { enum: SECTIONS }) }), - run: (s, a) => s.call('schema', a.section), + run: page('schema'), }, { name: 'catalog', description: 'The game\'s reference tables, which the argument domains point at: CITIES, NETS, CABLES, PORT, LT, OPT, DF_SYS, FAB, INTERNS, OPSK, CHARTERS, SCN, BANKS… plus three made for you: conferences (the upcoming calendar with the keys confGo and confSponsor take), TE_RECIPES (each RouteScript recipe with its script, ready for teDeploy) and BADGES (as the badge wall shows them). Omit name for the list of tables with their sizes.', inputSchema: obj({ name: str('One table; omit for the list.') }), - run: (s, a) => s.call('catalog', a.name), + run: page('catalog'), }, { name: 'state', description: 'The saved game itself as JSON, the same object the game saves: offers, loan offers, links, ports, PNIs, customers, the intern, events… with their ids. schema section "state" documents each field. Give a path (pops.fra, links, loanOffers, biz.3, links.): the whole state of a big network is hundreds of KB.', inputSchema: obj({ path: str('Dotted path: a key, an array index or an entity id per step.') }), - run: (s, a) => s.call('state', a.path), + run: page('state'), }, { name: 'results', description: 'The game\'s last traffic computation (R), rebuilt after every action and every day: load per link, use per port, demand and served per city, egress per network, monthly cost and revenue by kind, latency, reach. schema section "results" documents each field. Give a path (load, cost, netEg.ggl).', inputSchema: obj({ path: str('Dotted path.') }), - run: (s, a) => s.call('results', a.path), + run: page('results'), }, { name: 'ui', description: 'The view state actions read and write (the selection, the pending link pair, the drafts of the link, fiber and cable windows, the RouteScript draft, confirmations), without render caches. For working out why an action did what it did.', inputSchema: obj(), - run: (s) => s.call('ui'), + run: page('ui'), }, { name: 'actions', description: 'Every action act can run, with its arguments (? marks an optional one), e.g. buildPop(city), buyTransit(city,net,tier), buildLink(a,b,tier,cable?,route?,premiumCrossing?). Port tiers: 0 = 10G, 1 = 100G, 2 = 400G, 3 = 800G. Exchanges are given as city=. schema has each one\'s argument domains and what it does.', inputSchema: obj(), run: (s) => { - const { typed, drafts } = s.call('actions'), a = actArgs(); + const { typed, drafts } = s.call('actions', {}), a = actArgs(); return [...Object.entries(typed).map(([k, sig]) => `${k}(${sig})`), ...drafts.map((k) => (a[k] ? `${k}(${a[k].join(',')})` : k))].sort(); }, }, @@ -175,36 +186,32 @@ const TOOLS = [ description: 'Do something in the game: run one action with its arguments (see actions and schema). Arguments are checked first (a wrong id or value is an error that lists what fits); the action then runs as the game runs it: windows that take typed text are filled in (renameGo, teDeploy, teCheck, metricSet), multi-step builds take their choices as arguments (buildLink, orderDf, orderCable, decomGo), and confirmations are given (rmLink, cancelTransit…). outcome says what happened: applied (something changed), rejected (the game said no, see toasts), no_effect (nothing changed and nothing was said), shown (a view or draft: only the screen changed), decision (a window asks a question: answer with one of decision.options or closeModal; other game commands wait), quote (dryRun), stopped (bankrupt). charged is what the money gate took; cashChange also counts goal rewards. With dryRun, a game command is priced with the game\'s own helpers and nothing happens.', inputSchema: obj({ action: str('Action name, e.g. buildPop (view. prefixes are accepted).'), command: str('Same as action.'), args: { type: 'object', description: 'Its arguments, e.g. {"city":"ams"}.' }, dryRun: bool('Price it and check it can be done: {setup, monthly, days, blocked}. Nothing happens.') }), - run: (s, a) => { - const name = a.action || a.command; - if (!name) throw new Error('Give action, e.g. {"action":"buildPop","args":{"city":"ams"}}.'); - return s.call('run', name, a.args || {}, { dryRun: !!a.dryRun }); - }, + run: page('act'), }, { name: 'screen', description: 'What the player sees, as text with numbered buttons for click: the open window, else the bank or the NOC dashboard when open, else the side panel, else the puzzle box. where picks one: modal, bank, dash, panel, left (the left drawer: goals, deals, noc or nets) or puzzle. open lists what is showing. Long text comes in pages: textMore says the offset of the next one. Lists the game acts on when they change come with their options; click them with a value.', inputSchema: obj({ where: str('Which surface', { enum: WHERE }), offset: num('Start the text here (from textMore).') }), - run: (s, a) => s.call('screen', a.where, a.offset), + run: page('screen'), }, { name: 'panel', description: 'Open the side panel of a city or a link, a network in the network list, or a tab of the left drawer (goals, deals: offers and loans, noc, nets), optionally on a tab (a city has cust, up, peer, infra…), and show it as text with numbered buttons.', inputSchema: obj({ city: str('City id or name.'), link: str('Link id (from status, hot_spots or state links).'), network: str('Network id or name.'), tab: str('Tab id, as the tab buttons name it.'), left: str('A tab of the left drawer', { enum: ['goals', 'deals', 'noc', 'nets'] }) }), - run: (s, a) => s.call('panel', a), + run: page('panel'), }, { name: 'click', description: 'Press a numbered button from the last screen, panel or act result, as a player\'s click does: with the button\'s own arguments, so confirmations arm first and windows step on as in the game. For a list (it has options), give value.', inputSchema: obj({ button: num('The button\'s n.'), value: str('For a list: the option to pick.') }, ['button']), - run: (s, a) => s.call('click', a.button, a.value), + run: page('click'), }, { name: 'open_link', description: 'Open the build window for a link (a leased wave, dark fiber or your own cable) from one of your POPs to any city, to compare the routes and sizes it offers; then click through it. act buildLink, orderDf and orderCable do the same in one call.', inputSchema: obj({ from: str('One of your POPs.'), to: str('Any city.') }, ['from', 'to']), - run: (s, a) => s.call('openLink', a.from, a.to), + run: page('open_link'), }, ]; diff --git a/scripts/lib/mcp-headless.js b/scripts/lib/mcp-headless.js new file mode 100644 index 0000000..5c6a05d --- /dev/null +++ b/scripts/lib/mcp-headless.js @@ -0,0 +1,34 @@ +// Runs inside the MCP server's own game page (scripts/lib/mcp-game.js), in the game's global scope, after the page has +// loaded: the half of a session only that page has. It starts, loads and exports games, which in a player's browser +// are the player's alone, so it is not part of any page. Everything else a tool does goes through the page's own +// facade (window.TUBES, src/agent/). +(() => { + // Out of the way of the game: no sheet of a previous game, no title screen or pitch, the clock left to the server. + const settle = () => { UI.started = true; UI.pitched = true; UI.speed = 0; if (UI.pendGame) ACT.pitchSkip(); closeModal(); API_SHEET = null; compute(); renderAll(); }; + const newGame = ({ city = 'fra', name, preset = 'oncall', seed, asn, chaos } = {}) => { + const c = apiCityOf(city).id; + if (!homeOk(c)) apiFail(`${apiCityName(c)} cannot be a home city.`); + if (!['soft', 'freeze', 'oncall', 'bgp', 'sandbox'].includes(preset)) apiFail('preset is one of soft, freeze, oncall, bgp, sandbox'); + if (asn !== undefined && !asnOk(+asn)) apiFail(`AS${asn} cannot be yours: it is reserved, private or another network's. Leave asn out for a free one.`); + if (chaos !== undefined && preset !== 'sandbox') apiFail('chaos is the sandbox\'s dial: give preset "sandbox" with it.'); + if (chaos !== undefined && !own(CHAOS, chaos)) apiFail(`chaos is one of ${Object.keys(CHAOS).join(', ')}.`); + if (seed !== undefined && window.__reseed) window.__reseed(Math.max(1, Math.floor(+seed) || 1)); + if (UI.pendGame) UI.pendGame = null; + UI.pitched = true; + const nm = String(name || randomNetworkName()).slice(0, 24), was = UI.asnTxt; + // beginGame takes the ASN typed on the title screen. + UI.asnTxt = asn !== undefined ? String(+asn) : ''; + try { beginGame(nm, c, preset === 'sandbox' ? { mode: 'sandbox', rules: { chaos: chaos || 'none' } } : { mode: 'normal', preset }); } finally { UI.asnTxt = was; } + settle(); + return apiStatus(); + }; + const loadSave = (txt) => { + const r = parseSave(txt); + if (r.err) apiFail(apiText(r.err)); + S = migrate(JSON.parse(JSON.stringify(r.s))); + settle(); + return { savedBy: r.ver, ...apiStatus() }; + }; + const exportSave = (version) => JSON.stringify({ app: 'series-of-tubes', version: /^\d/.test(APP_VERSION) ? APP_VERSION : version, exported: new Date().toISOString(), S: packSave(S) }); + window.__mcpHeadless = { newGame, loadSave, exportSave }; +})(); diff --git a/scripts/lib/mcp-page.js b/scripts/lib/mcp-page.js deleted file mode 100644 index 2eb6717..0000000 --- a/scripts/lib/mcp-page.js +++ /dev/null @@ -1,487 +0,0 @@ -// Runs inside the game page (see scripts/lib/mcp-game.js), in the game's own global scope, so it reads S, R, NET, -// CITY… directly. Every function takes and returns plain JSON. It only reads the game, except run(), click(), -// panel(), advance() and the game loaders, which go through the same ACT actions and dayTick() the page uses. -// The command tables run() checks arguments against come from scripts/lib/mcp-commands.js, evaluated first. -(() => { - const { API_DOMAINS, API_CMD, API_VIEW, API_BOUND, API_SESSION, API_STATE_DOC, API_RESULTS_DOC, API_TABLES, API_MADE, - API_UI_HIDDEN, apiDomCheck, apiDomValues, apiPath, apiJson } = window.__mcpCmds; - const BLOCK = /^(DIV|P|H1|H2|H3|H4|SECTION|LI|UL|OL|TR|TABLE|NAV|HEADER|FOOTER|BUTTON|LABEL|DETAILS|SUMMARY)$/; - const MAX_TEXT = 8000; - // Text as a player would read it: one line per block, no runs of spaces. jsdom has no innerText. - const fullText = (x) => { - let el = x; - if (typeof x === 'string') { el = document.createElement('div'); el.innerHTML = x; } - if (!el) return ''; - const out = []; - const walk = (n) => { - if (n.nodeType === 3) { out.push(n.nodeValue); return; } - if (n.nodeType !== 1 || n.hidden || /^(SCRIPT|STYLE|SVG|CANVAS)$/i.test(n.tagName)) return; - if (n.tagName === 'BR') { out.push('\n'); return; } - // A dropdown reads as its choice: hundreds of options would crowd out the rest (the catalog lists them). - if (n.tagName === 'SELECT') { const o = n.options[n.selectedIndex]; out.push(' ', o ? o.text : '', ' '); return; } - // Blocks get their own line; inline tags a space, so "Revenue$2k" does not read as one word. - const sep = BLOCK.test(n.tagName) ? '\n' : ' '; - out.push(sep); - for (const c of n.childNodes) walk(c); - out.push(sep); - }; - walk(el); - return out.join('').split('\n').map((l) => l.replace(/\s+/g, ' ').replace(/ ([.,;:!?)])/g, '$1').replace(/\( /g, '(').trim()).filter(Boolean).join('\n'); - }; - const text = (x, max = MAX_TEXT) => { const s = fullText(x); return s.length > max ? s.slice(0, max) + '\n…' : s; }; - const r1 = (v) => (typeof v === 'number' && isFinite(v) ? Math.round(v * 10) / 10 : v); - const fail = (msg) => { throw new Error(msg); }; - const norm = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').trim(); - const parse = (s) => { try { return JSON.parse(s || '{}'); } catch (e) { return {}; } }; - - // ---------- finding things by id or by name ---------- - const best = (list, q, keys) => { - const n = norm(q); - if (!n) return null; - for (const test of [(v) => v === n, (v) => v.startsWith(n), (v) => v.includes(n)]) { - const hit = list.find((x) => keys(x).some((k) => test(norm(k)))); - if (hit) return hit; - } - return null; - }; - const netOf = (q) => NET[q] || best(NETS, q, (n) => [n.id, n.name, 'as' + n.asn, String(n.asn)]) || fail(`No network matches "${q}". Try find.`); - const cityOf = (q) => CITY[q] || best(CITIES, q, (c) => [c.id, c.name]) || fail(`No city matches "${q}". Try find.`); - const allIx = () => { - const o = []; - for (const c of CITIES) for (const x of ixStatic(c.id)) o.push(x); - for (const c of Object.keys(S.myIx || {})) if (!o.includes(c)) o.push(c); - return o; - }; - const cityName = (c) => (CITY[c] ? CITY[c].name : c); - const incText = (i) => text(i.msg || incTitle(i), 400); - - // ---------- toasts: what the game tells the player ---------- - let toasts = []; - const t0 = toast; - toast = function (h, kind) { toasts.push({ kind: kind || '', text: text(String(h), 600) }); return t0.apply(this, arguments); }; - const takeToasts = () => { const t = toasts; toasts = []; return t; }; - const toastLines = (t) => t.map((x) => (x.kind ? x.kind + ': ' : '') + x.text); - - // ---------- what is on screen ---------- - // The surfaces a player can read, by the name screen() takes. The left drawer has tabs (goals, deals, noc, nets). - const ROOT = { modal: 'modal', bank: 'bankBox', dash: 'dash', panel: 'panel', left: 'leftBody', puzzle: 'pzBox' }; - const shown = (w) => { const el = $(ROOT[w]); return !!el && !el.hidden; }; - const modalOpen = () => shown('modal'); - let last = []; - const controls = (root) => { - const out = []; - for (const b of root.querySelectorAll('[data-act],select[data-chg]')) { - if (b.dataset.act) out.push({ label: text(b, 200).replace(/\n/g, ' ') || b.getAttribute('aria-label') || b.dataset.act, act: b.dataset.act, args: parse(b.dataset.args), disabled: !!b.disabled }); - // A list the game acts on when its value changes (the change handler in src/game/96-map/95-clicks.js): click - // it with a value. - else out.push({ label: b.getAttribute('aria-label') || (b.closest('label') && text(b.closest('label'), 120).split('\n')[0]) || b.dataset.chg, - select: b.dataset.chg, value: b.value, options: [...b.options].map((o) => ({ value: o.value, label: o.textContent.trim() })), disabled: !!b.disabled }); - } - return out; - }; - const screen = (where, offset = 0) => { - if (where === null) where = undefined; - if (where !== undefined && !ROOT[where]) fail(`where is one of ${Object.keys(ROOT).join(', ')}.`); - const open = Object.keys(ROOT).filter((w) => w !== 'left' && shown(w)); - const w = where || ['modal', 'bank', 'dash', 'panel', 'puzzle'].find(shown) || 'panel'; - const root = $(ROOT[w]); - last = root ? controls(root) : []; - const all = root ? fullText(root) : '', from = Math.max(0, Math.floor(+offset) || 0), more = all.length - from - MAX_TEXT; - const out = { where: w, open, selected: UI.sel, tab: UI.tab }; - if (w === 'left') out.leftTab = UI.left || 'goals'; - if (w === 'modal') { const d = decision(); out.question = !!d; } - out.text = all.slice(from, from + MAX_TEXT); - if (from) out.textFrom = from; - if (more > 0) out.textMore = `${more} more characters: call screen with where "${w}" and offset ${from + MAX_TEXT}`; - out.buttons = last.map((b, i) => ({ n: i, ...b })); - return out; - }; - - // ---------- windows: the agent's own sheets, and the game's questions ---------- - // A window the agent opened itself (a view, a draft, the link window, a sheet it clicked inside) is something to read - // and click through. A window the game opened in answer to a game command, or during a day, is a question when one - // of its buttons runs a game command other than closeModal (a De-Kicks quote, a retention offer); then other game - // commands wait until it is answered or closed, as clicks outside an open window do in the game. - let sheet = null; - const card = () => $('modalCard').firstChild; - const markSheet = () => { sheet = modalOpen() ? card() : null; }; - const isSheet = () => modalOpen() && !!sheet && card() === sheet; - const decision = () => { - if (!modalOpen() || isSheet()) return null; - const b = [...$('modal').querySelectorAll('[data-act]')].filter((x) => x.dataset.act !== 'closeModal' && API_CMD[x.dataset.act]); - if (!b.length) return null; - return { text: text($('modal'), 1500), options: b.map((x) => ({ command: x.dataset.act, args: parse(x.dataset.args), label: text(x, 120).replace(/\n/g, ' ') })) }; - }; - - // ---------- starting and loading ---------- - const settle = () => { UI.started = true; UI.pitched = true; UI.speed = 0; if (UI.pendGame) ACT.pitchSkip(); closeModal(); sheet = null; compute(); renderAll(); takeToasts(); }; - const newGame = ({ city = 'fra', name, preset = 'oncall', seed, asn, chaos }) => { - const c = cityOf(city).id; - if (!homeOk(c)) fail(`${cityName(c)} cannot be a home city.`); - if (!['soft', 'freeze', 'oncall', 'bgp', 'sandbox'].includes(preset)) fail('preset is one of soft, freeze, oncall, bgp, sandbox'); - if (asn !== undefined && !asnOk(+asn)) fail(`AS${asn} cannot be yours: it is reserved, private or another network's. Leave asn out for a free one.`); - if (chaos !== undefined && preset !== 'sandbox') fail('chaos is the sandbox\'s dial: give preset "sandbox" with it.'); - if (chaos !== undefined && !own(CHAOS, chaos)) fail(`chaos is one of ${Object.keys(CHAOS).join(', ')}.`); - if (seed !== undefined && window.__reseed) window.__reseed(Math.max(1, Math.floor(+seed) || 1)); - if (UI.pendGame) UI.pendGame = null; - UI.pitched = true; - const nm = String(name || randomNetworkName()).slice(0, 24), was = UI.asnTxt; - // beginGame takes the ASN typed on the title screen. - UI.asnTxt = asn !== undefined ? String(+asn) : ''; - try { beginGame(nm, c, preset === 'sandbox' ? { mode: 'sandbox', rules: { chaos: chaos || 'none' } } : { mode: 'normal', preset }); } finally { UI.asnTxt = was; } - settle(); - return status(); - }; - const loadSave = (txt) => { - const r = parseSave(txt); - if (r.err) fail(text(r.err)); - S = migrate(JSON.parse(JSON.stringify(r.s))); - settle(); - return { savedBy: r.ver, ...status() }; - }; - const exportSave = (version) => JSON.stringify({ app: 'series-of-tubes', version: /^\d/.test(APP_VERSION) ? APP_VERSION : version, exported: new Date().toISOString(), S: packSave(S) }); - - // ---------- reading the network ---------- - const status = () => { - const goal = GOALS.find((g) => S.done[g.id] === undefined); - const t1 = isTier1(); - return { - name: S.name, asn: S.asn, home: cityName(S.home), mode: S.mode, rules: S.rules && S.rules.preset, - day: S.day, date: dateStr(S.day), cash: Math.round(S.cash), level: S.lvl || 0, - tier: tierLabel(), whyNotTier1: t1 ? null : text(t1Why()), - goal: goal ? { title: text(goal.t), what: text(goal.d) } : null, - monthly: { revenue: Math.round(R.revMo), cost: Math.round(R.costMo), profit: Math.round(R.revMo - R.costMo), - revenueBy: Object.fromEntries(Object.entries(R.rev || {}).map(([k, v]) => [k, Math.round(v)]).filter(([, v]) => v)), - costBy: Object.fromEntries(Object.entries(R.cost || {}).map(([k, v]) => [k, Math.round(v)]).filter(([, v]) => v)) }, - traffic: { demandGbps: r1(R.demand), servedGbps: r1(R.served), reach: r1((R.reach || 0) * 100) + '%', peeringSessions: R.sessions }, - counts: { pops: Object.keys(S.pops).length, links: S.links.length, transitPorts: S.transit.length, exchangePorts: Object.keys(S.ixp).length, - pnis: S.pni.length, cacheBoxes: S.caches.length, customers: S.biz.length, offers: S.offers.length }, - pops: Object.keys(S.pops).map(cityName), - incidents: S.inc.map((i) => ({ id: i.id, type: i.type, what: incText(i), until: i.until !== undefined ? dateStr(i.until) : undefined, rushRepairCost: i.cost || undefined })), - lost: !!S.lost, won: !!S.won, - }; - }; - - const network = (q) => { - const n = netOf(q), id = n.id, eg = R.netEg && R.netEg[id]; - return { - id, name: n.name, asn: n.asn, type: TYPE_L[n.type], policy: n.pol, - requirements: { minIxGbps: n.minIx, minPniGbps: n.minPni, paidFeePerMonth: n.paidFee, freeFromLevel: n.freeLv }, - trafficShare: r1(NSH[id] * 100) + '%', transitPerGbps: n.price ? r1(n.price * S.priceMul) : null, - homeMarkets: n.cc ? [].concat(n.cc) : [], pops: n.pops.map(cityName), - exchanges: n.ix === 'ALL' ? 'most exchanges where it has a PoP' : (n.ix || []).map((x) => ixName(x)), - upstreams: (n.up || []).map((u) => NET[u] ? NET[u].name : u), customerCone: (DOWN[id] || []).length, - neededForTier1: t1Need().some((x) => x.id === id), mergedInto: merged(id) ? (MERGERS.find((m) => m.id === id) || {}).into : undefined, - about: text(n.blurb), - you: { - reachable: !!(R.reachable && R.reachable[id]), demandGbps: r1((R.demTo && R.demTo[id]) || 0), - egressGbps: eg ? Object.fromEntries(Object.entries(eg).map(([k, v]) => [k, r1(v)])) : null, - pnis: S.pni.filter((p) => p.net === id).map((p) => ({ id: p.id, city: cityName(p.city), port: pniPN(p), count: p.n || 1, ready: pniOn(p) })), - exchangeSessions: Object.keys(S.ixp).filter((x) => ixSessions(x).has(id)).map(ixName), - howToPeer: text(offTransitHint(id, S.home)), - }, - }; - }; - - const city = (q) => { - const C = cityOf(q), c = C.id, P = S.pops[c]; - const cab = CABLE_PAIRS.filter((p) => p.a === c || p.b === c).map((p) => ({ cable: CAB[p.cid] ? CAB[p.cid].name : p.cid, to: cityName(p.a === c ? p.b : p.a), km: p.km })); - const here = NETS.filter((n) => n.pops.includes(c) && !n.tail).sort((a, b) => b.share - a.share); - return { - id: c, name: C.name, country: C.cc, region: C.reg, about: C.note ? text(C.note) : undefined, dataCenter: C.dc, - canBeHome: homeOk(c), - exchanges: ixIdsIn(c).map((x) => ({ id: x, name: ixName(x), members: ixMembers(x).length, yourPort: S.ixp[x] !== undefined })), - transit: NETS.filter((n) => sellsAt(n, c)).map((n) => ({ id: n.id, name: n.name, type: TYPE_L[n.type], perGbps: r1(transitPerG(n, c, false) * S.priceMul) })).sort((a, b) => a.perGbps - b.perGbps), - networksHere: here.length, biggestNetworksHere: here.slice(0, 15).map((n) => n.name), cables: cab, - you: P ? { demandGbps: r1((R.cityDem || {})[c] || 0), servedGbps: r1((R.citySrv || {})[c] || 0), routers: P.routers, down: P.down > S.day ? dateStr(P.down) : false, - broadband: !!P.bb, links: S.links.filter((l) => l.a === c || l.b === c).length } : null, - }; - }; - - const find = (q, kind) => { - const n = norm(q), hit = (...k) => k.some((v) => norm(v).includes(n)), out = {}; - if (!n) fail('Give a word to search for.'); - if (!kind || kind === 'city') out.cities = CITIES.filter((c) => hit(c.id, c.name)).slice(0, 20).map((c) => ({ id: c.id, name: c.name, country: c.cc })); - if (!kind || kind === 'network') out.networks = NETS.filter((x) => hit(x.id, x.name, String(x.asn))).slice(0, 20).map((x) => ({ id: x.id, name: x.name, asn: x.asn, type: TYPE_L[x.type] })); - if (!kind || kind === 'cable') out.cables = Object.values(CAB).filter((x) => hit(x.id, x.name)).slice(0, 20).map((x) => ({ id: x.id, name: x.name, lands: [...new Set(x.pairs.flatMap((p) => [p[0], p[1]]))].map(cityName) })); - if (!kind || kind === 'exchange') out.exchanges = allIx().filter((x) => hit(x, ixName(x))).slice(0, 20).map((x) => ({ id: x, name: ixName(x), city: cityName(ixCity(x)) })); - return out; - }; - - const trace = (from, to) => { - const src = cityOf(from).id; - if (!S.pops[src]) fail(`You have no POP in ${cityName(src)}. Yours: ${Object.keys(S.pops).map(cityName).join(', ')}.`); - let target = null; - if (typeof to === 'string' && /^city:/i.test(to)) target = { city: cityOf(to.slice(5)).id }; - else { try { target = { net: netOf(to).id }; } catch (e) { target = { city: cityOf(to).id }; } } - if (target.city && !S.pops[target.city]) fail(`A traceroute to a city goes to one of your POPs: ${Object.keys(S.pops).map(cityName).join(', ')}.`); - const r = traceroute(src, target); - return { text: r.text, why: text(r.why || ''), asPath: r.asPath || null }; - }; - - const peering = (q, where, via) => { - const n = netOf(q), id = n.id, out = []; - if (!via || via === 'pni') for (const c of (where ? [cityOf(where).id] : Object.keys(S.pops).filter((c) => n.pops.includes(c)))) { - const r = peerOk(id, 'pni', c); - out.push({ via: 'pni', city: cityName(c), ok: !!r.ok, why: r.why ? text(r.why) : undefined, feePerMonth: r.fee, free: r.free, minimumPort: PORT[pniMin(id)].n }); - } - if (!via || via === 'ix') for (const x of Object.keys(S.ixp).filter((x) => ixMembers(x).includes(id) && (!where || ixCity(x) === cityOf(where).id))) { - const r = peerOk(id, 'ix', x); - out.push({ via: 'ix', exchange: ixName(x), ok: !!r.ok, why: r.why ? text(r.why) : undefined, session: ixSessions(x).has(id) }); - } - return { network: n.name, policy: n.pol, hint: text(offTransitHint(id, where ? cityOf(where).id : S.home)), - checks: out, note: out.length ? undefined : 'No POP or exchange port of yours is where this network is. Build one first: see network.' }; - }; - - const hotSpots = (limit = 10) => { - const top = (a) => a.sort((x, y) => y.util - x.util).slice(0, limit); - const pct = (u, c) => (c > 0 ? r1((u / c) * 100) : null); - const links = S.links.map((l) => { const cap = capOf(l), u = (R.load || {})[l.id] || 0; return { id: l.id, between: cityName(l.a) + ' – ' + cityName(l.b), kind: l.kind, capacity: capName(l), usedGbps: r1(u), util: pct(u, cap), down: linkDown(l) }; }); - const transit = S.transit.map((t) => { const cap = lagCap(PORT[t.tier].g, t.n), u = (R.useT || {})[t.id] || 0, q = (R.p95 && R.p95[t.id]) || u; - return { id: t.id, city: cityName(t.city), carrier: NET[t.net].name, port: lagName(t.tier, t.n), usedGbps: r1(u), util: pct(u, cap), billPerMonth: Math.round(transitMo(t, q)) }; }); - const pnis = S.pni.filter(pniOn).map((p) => { const cap = pniG(p) * (p.n || 1), u = (R.usePni || {})[p.id] || 0; return { id: p.id, network: NET[p.net].name, city: cityName(p.city), port: pniPN(p), usedGbps: r1(u), util: pct(u, cap) }; }); - const viaTransit = NETS.filter((n) => R.netEg && R.netEg[n.id] && R.netEg[n.id].t > 0.05).sort((a, b) => R.netEg[b.id].t - R.netEg[a.id].t).slice(0, limit) - .map((n) => ({ id: n.id, network: n.name, overTransitGbps: r1(R.netEg[n.id].t), howToPeer: text(offTransitHint(n.id, S.home)) })); - const bill = {}; - for (const t of transit) bill[t.carrier] = (bill[t.carrier] || 0) + t.billPerMonth; - return { links: top(links), transitPorts: top(transit), pnis: top(pnis), transitBillByCarrier: bill, biggestTrafficStillOnTransit: viaTransit }; - }; - - // ---------- the contract: commands, arguments, reference tables, raw state ---------- - // Actions the server never runs: files, storage slots, settings and the title screen are not the game's, and time - // only moves through advance. - const WHY = { - time: 'use advance to move time', start: 'use new_game', files: 'use load_save or export_save', - slots: 'saved networks in browser storage are not part of this game', prefs: 'device and player settings are not part of the game', - browser: 'it needs the browser itself (a share sheet, the clipboard, an install prompt or a reload)', - }; - const DENY_WHY = { - speed: 'time', phonePlay: 'time', phoneSpeed: 'time', - start: 'start', newgame: 'start', cont: 'start', toTitle: 'start', resetAsk: 'start', - exportSave: 'files', importGo: 'files', importPick: 'files', slotExport: 'files', - slotBack: 'slots', slotDel: 'slots', slotDelGo: 'slots', slotMenu: 'slots', slotRetry: 'slots', slotSpace: 'slots', slotSwitch: 'slots', slotTake: 'slots', - animSet: 'prefs', langSet: 'prefs', menu: 'prefs', mute: 'prefs', prefSet: 'prefs', settings: 'prefs', settingsClose: 'prefs', soundSet: 'prefs', vpSet: 'prefs', - install: 'browser', share: 'browser', shareDl: 'browser', shareGo: 'browser', traceCopy: 'browser', updateLater: 'browser', updateNow: 'browser', wsShare: 'browser', pzShare: 'browser', - }; - const denied = (name) => (Object.prototype.hasOwnProperty.call(DENY_WHY, name) ? WHY[DENY_WHY[name]] : null); - const kindOf = (name) => (API_CMD[name] ? 'game' : API_VIEW[name] ? 'view' : API_BOUND[name] ? 'draft' : API_SESSION[name] ? 'session' : null); - const specOf = (name) => API_CMD[name] || API_VIEW[name] || API_SESSION[name] || null; - const classes = () => ({ game: Object.keys(API_CMD), view: Object.keys(API_VIEW), draft: Object.keys(API_BOUND), session: Object.keys(API_SESSION), denied: Object.keys(DENY_WHY) }); - - // One argument as the schema states it. Table domains name their catalog table rather than list every id. - const argDoc = ([name, dom, req]) => { - const a = { name, required: req !== false }, d = API_DOMAINS[dom]; - if (!d) { a.type = dom; return a; } - a.domain = dom; - if (d.table) a.from = d.table; - else { const v = apiDomValues(dom); if (Array.isArray(v)) a.values = v; else if (v && v.from !== undefined) a.range = v; } - return a; - }; - const schema = (section) => { - const cmd = (s) => ({ args: (s.args || []).map(argDoc), doc: s.doc }); - const doc = { - clock: 'Time moves only with advance: one dayTick() per simulated day, as the game loop runs it. Nothing runs between calls.', - commands: Object.fromEntries(Object.entries(API_CMD).map(([n, s]) => [n, { ...cmd(s), dryRun: !!s.quote, - ...(s.decides ? { decides: true } : {}), ...(s.confirm ? { confirm: s.confirm } : {}), ...(s.open ? { opens: s.open } : {}), ...(s.reads ? { report: true } : {}) }])), - view: Object.fromEntries(Object.entries(API_VIEW).map(([n, s]) => [n, cmd(s)])), - session: Object.fromEntries(Object.entries(API_SESSION).map(([n, s]) => [n, cmd(s)])), - drafts: API_BOUND, - denied: Object.fromEntries(Object.keys(DENY_WHY).sort().map((n) => [n, denied(n)])), - domains: Object.fromEntries(Object.entries(API_DOMAINS).map(([n, d]) => { const v = apiDomValues(n); - return [n, { kind: d.kind === 'fn' ? 'custom' : d.kind, ...(d.table ? { from: d.table } : {}), - ...(!d.table && Array.isArray(v) ? { values: v } : v && v.from !== undefined ? { range: v } : v && v.of ? { of: v.of } : {}) }]; })), - state: API_STATE_DOC, results: API_RESULTS_DOC, - }; - if (section === undefined || section === null || section === '') return doc; - if (!(section in doc)) fail(`No section "${section}". Sections: ${Object.keys(doc).join(', ')}.`); - return doc[section]; - }; - const catalog = (name) => { - if (name === undefined || name === null || name === '') { - return { tables: [...Object.keys(API_TABLES), ...Object.keys(API_MADE)].sort().map((k) => { const t = k in API_MADE ? API_MADE[k]() : API_TABLES[k]; - return { name: k, n: Array.isArray(t) ? t.length : t && typeof t === 'object' ? Object.keys(t).length : 1 }; }) }; - } - if (name in API_MADE) return apiJson(API_MADE[name]()); - if (name in API_TABLES) return apiJson(API_TABLES[name]); - fail(`No table "${name}". Call catalog without a name for the list.`); - }; - const state = (path) => { if (!S) return null; const v = apiJson(apiPath(S, path)); return v === undefined ? null : v; }; - const results = (path) => { const v = apiJson(apiPath(R, path)); return v === undefined ? null : v; }; - const ui = () => { const o = {}; for (const k of Object.keys(UI)) if (!API_UI_HIDDEN[k]) o[k] = apiJson(UI[k]); return o; }; - const actions = () => { - const sig = (s) => (s.args || []).map((a) => a[0] + (a[2] === false ? '?' : '')).join(','); - const typed = {}; - for (const t of [API_CMD, API_VIEW, API_SESSION]) for (const [n, s] of Object.entries(t)) typed[n] = sig(s); - return { typed, drafts: Object.keys(API_BOUND) }; - }; - - // ---------- doing things ---------- - // Arguments: shape and domain only. Anything beyond that is the game's to answer. - const validate = (spec, args) => { - const problems = [], out = {}; - for (const [name, dom, req] of spec.args || []) { - const v = args[name]; - if (v === undefined) { if (req !== false) problems.push(`${name} is required`); continue; } - if (apiDomCheck(dom, v).ok) { out[name] = v; continue; } - const vs = apiDomValues(dom), d = API_DOMAINS[dom]; - problems.push(`${name}: ${JSON.stringify(v)} is not a ${dom}${d && d.table && d.kind === 'id' ? ` (see catalog ${d.table} or find)` : Array.isArray(vs) ? ` (one of ${vs.slice(0, 12).join(', ')}${vs.length > 12 ? '…' : ''})` : vs && typeof vs === 'object' && vs.from !== undefined ? ` (${vs.from}..${vs.to})` : ''}`); - } - for (const k of Object.keys(args)) if (!(spec.args || []).some((a) => a[0] === k)) problems.push(`${k} is not an argument of this action`); - return { ok: !problems.length, problems, args: out }; - }; - // The fingerprint tells "did nothing" from "did something quietly": cash, day, the entity counts, the small - // settings maps, and the paths a command declares in watch. R is left out: it is rebuilt after every action. - const FP_LEN = ['links', 'transit', 'pni', 'caches', 'biz', 'offers', 'nni', 'loans', 'loanOffers', 'inc', 'scrubs']; - const FP_KEYS = ['pops', 'ixp', 'peers', 'myIx', 'done', 'ach', 'merged', 'confReg']; - const FP_JSON = ['name', 'pairMet', 'rs', 'ixn', 'ixSite', 'ixPref', 'spares', 'te', 'cnLic', 'hw', 'scrubMode', 'ppol', 'ops', 'core', 'ddosAuto', 'popStd', 'demo', 'charter', 'monkey', 'seatOff', 'pz', 'ar', 'dk', 'ev']; - const fp = (watch, args) => { - if (!S) return null; - const f = { cash: S.cash, day: S.day, lvl: S.lvl || 1, won: !!S.won, lost: !!S.lost }; - for (const k of FP_LEN) f[k] = (S[k] || []).length; - for (const k of FP_KEYS) f[k] = Object.keys(S[k] || {}).length; - for (const k of FP_JSON) f[k] = JSON.stringify(apiJson(S[k]) ?? null); - for (const p of watch || []) f['@' + p] = JSON.stringify(apiJson(apiPath(S, String(p).replace(/#(\w+)/g, (m, k) => (args && args[k] !== undefined ? args[k] : m)))) ?? null); - return JSON.stringify(f); - }; - // spend() is the game's money gate and a top-level function, so every action reaches it by its global name. - const meter = () => { const real = window.spend; let paid = 0; window.spend = (c) => { const ok = real(c); if (ok) paid += c; return ok; }; return () => { window.spend = real; return paid; }; }; - - // One action, run as the game runs it, and reported: what the game said (toasts), what it charged at the money gate - // (goal rewards that land in the same call are not a price), whether anything changed, and what is on screen now. - // typed: through the command table (bind the UI, type into fields, pass the confirmation); otherwise as a button - // click does it, with the button's own arguments. - const dispatch = (name, kind, spec, args, typed) => { - const mine = isSheet() || (typed && kind === 'game' && !!spec.open); - takeToasts(); - const ref = S, cash = S ? S.cash : 0, f0 = fp(spec && spec.watch, args), paid = meter(); - let threw = null, report; - try { - if (typed && kind === 'game') { - if (spec.open) { ACT[spec.open]({}); markSheet(); } - // The custom metric's field lives in the link's panel. - if (name === 'metricSet' && !$('metIn')) { UI.sel = { type: 'link', id: args.id }; renderAll(); } - const gone = (spec.dom || []).filter((f) => !$(f)); - if (gone.length) throw new Error(`the field it types into (${gone.join(', ')}) is not on screen${name === 'metricSet' ? ': set the link\'s metric to custom first (setMetric v "custom")' : ''}`); - if (spec.bind) spec.bind(args); - const a = spec.pass ? spec.pass(args) : args; - ACT[name](a); - if (spec.confirm === 'double') ACT[name](a); - if (spec.reads === 'modal' && modalOpen()) { report = text($('modal')); closeModal(); } - } else ACT[name](args); - } catch (e) { threw = e; } - const charged = paid(); - if (threw) { takeToasts(); fail(`${name} failed: ${threw && threw.message || threw}`); } - if (!modalOpen()) sheet = null; - else if (mine || kind !== 'game') markSheet(); - else sheet = null; - const said = takeToasts(), d = decision(); - const outcome = d ? 'decision' : S !== ref || fp(spec && spec.watch, args) !== f0 || report !== undefined ? 'applied' - : said.some((t) => t.kind === 'bad') ? 'rejected' : kind === 'view' || kind === 'draft' ? 'shown' : 'no_effect'; - return { action: name, outcome, toasts: toastLines(said), charged, cashChange: Math.round((S ? S.cash : 0) - cash), - ...(report !== undefined ? { report } : {}), ...(d ? { decision: d } : {}), screen: screen() }; - }; - // While the game waits for an answer, game commands other than its options report the question instead. - const waiting = (name) => { - const d = decision(); - return d && name !== 'closeModal' && !d.options.some((o) => o.command === name) - ? { action: name, outcome: 'decision', reason: 'A window is waiting for an answer: run one of its options, or closeModal.', decision: d, screen: screen() } : null; - }; - const quote = (name, spec, args) => { - const ui0 = {}; - for (const k of spec.bindsUI || []) ui0[k] = UI[k]; - const f0 = fp(spec.watch, args); - // A dry run must not use up the dice: some helpers draw (a PNI's lead time), and a draw here would move the seeded - // game. They get the middle of the range instead, so a drawn figure in a quote is a typical one. - const dice = Math.random; - Math.random = () => 0.5; - let q = {}; - try { - if (spec.bind && !spec.dom) spec.bind(args); - if (spec.quote) q = spec.quote(args) || {}; - } catch (e) { fail(`${name}: the price could not be worked out: ${e && e.message || e}`); } finally { Math.random = dice; for (const k of Object.keys(ui0)) UI[k] = ui0[k]; } - return { action: name, outcome: 'quote', quote: { setup: 0, monthly: 0, ...q, blocked: (q.blocked || []).map((b) => text(String(b), 400)) }, consistent: fp(spec.watch, args) === f0, - ...(spec.quote ? {} : { note: 'This command has no price of its own: it costs nothing up front.' }) }; - }; - const run = (name, args, opts = {}) => { - name = String(name || ''); - if (name.startsWith('view.')) name = name.slice(5); - const no = denied(name); - if (no) fail(`${name} is not available here: ${no}.`); - const kind = kindOf(name); - if (!kind || typeof ACT[name] !== 'function') fail(`There is no action "${name}". See actions or schema.`); - args = args && typeof args === 'object' && !Array.isArray(args) ? args : {}; - const spec = specOf(name); - if (spec) { const v = validate(spec, args); if (!v.ok) fail(`${name}: ${v.problems.join('; ')}. See schema for its arguments.`); args = v.args; } - if (kind === 'game') { - if (S && S.lost && name !== 'closeModal') return { action: name, outcome: 'stopped', reason: 'The network went bankrupt: start or load another game.' }; - const w = waiting(name); - if (w) return w; - if (opts.dryRun) return quote(name, spec, args); - } else if (opts.dryRun) fail(`${name} has no price: only game commands (see schema commands) dry-run.`); - return dispatch(name, kind, spec, args, true); - }; - const click = (n, value) => { - const b = last[n]; - if (!b) fail(`No button ${n} on the last screen. Call screen first.`); - if (b.disabled) fail(`"${b.label}" is greyed out.`); - const name = b.select || b.act, args = b.select ? { v: value === undefined ? undefined : String(value) } : b.args; - if (b.select && !b.options.some((o) => o.value === args.v)) fail(`"${b.label}" is a list: click it with a value, one of ${b.options.map((o) => JSON.stringify(o.value)).join(', ')}.`); - const no = denied(name); - if (no) fail(`${name} is not available here: ${no}.`); - const kind = kindOf(name); - if (!kind || typeof ACT[name] !== 'function') fail(`"${b.label}" runs ${name}, which is not an action.`); - if (kind === 'game') { const w = waiting(name); if (w) return { clicked: b.label, ...w }; } - return { clicked: b.label, ...dispatch(name, kind, specOf(name), args, false) }; - }; - const panel = ({ city: c, link, network: q, tab, left }) => { - if (left !== undefined) { if (!['goals', 'deals', 'noc', 'nets'].includes(left)) fail('left is one of goals, deals, noc, nets.'); ACT.leftTab({ t: left }); return screen('left'); } - if (c) UI.sel = { type: 'city', id: cityOf(c).id }; - else if (link) { if (!S.links.some((l) => l.id === link)) fail(`No link ${link}. See status or hot_spots for link ids.`); UI.sel = { type: 'link', id: link }; } - else if (q) ACT.netFocus({ id: netOf(q).id }); - if (tab) UI.tab = tab; - renderAll(); - return screen(q ? 'left' : 'panel'); - }; - const openLink = (a, b) => { - const x = cityOf(a).id, y = cityOf(b).id; - if (!S.pops[x]) fail(`A link starts at one of your POPs: ${Object.keys(S.pops).map(cityName).join(', ')}.`); - takeToasts(); - openLinkModal(x, y); - markSheet(); - return { toasts: toastLines(takeToasts()), screen: screen() }; - }; - - // ---------- time ---------- - const advance = (days = 1) => { - days = Math.max(1, Math.min(3650, Math.floor(+days) || 1)); - if (modalOpen()) fail('A window is open. Answer it first (screen, click, or act closeModal), the game does not run days behind it.'); - sheet = null; - const start = S.day, cash = S.cash, inc0 = new Set(S.inc.map((i) => i.id)), times = []; - takeToasts(); - let ran = 0, stop = null; - while (ran < days) { - if (S.lost) { stop = 'bankrupt'; break; } - const t = performance.now(); - dayTick(); - times.push({ day: S.day, ms: r1(performance.now() - t) }); - ran++; - if (modalOpen()) { stop = 'a window opened'; break; } - } - renderAll(); - // The log keeps what mattered; toasts that only repeat a log line are left out. - const entries = (S.log || []).filter((e) => e.d > start).slice(-60), logged = entries.map((e) => norm(text(e.t, 400))); - const log = entries.map((e) => `${dateStr(e.d)}: ${text(e.t, 400)}`); - const total = times.reduce((a, x) => a + x.ms, 0), d = stop === 'a window opened' ? decision() : null; - return { - from: dateStr(start), to: dateStr(S.day), daysRun: ran, stoppedBecause: stop, cash: Math.round(S.cash), cashChange: Math.round(S.cash - cash), - newIncidents: S.inc.filter((i) => !inc0.has(i.id)).map(incText), - log, toasts: [...new Set(toastLines(takeToasts()))].filter((t) => { const f = norm(t.replace(/^\w+: /, '').split('\n')[0]); return !logged.some((l) => l.startsWith(f)); }).slice(-40), - timing: { totalMs: r1(total), perDayMs: r1(total / (ran || 1)), slowestDays: times.slice().sort((a, b) => b.ms - a.ms).slice(0, 5).map((x) => ({ date: dateStr(x.day), ms: x.ms })) }, - ...(d ? { decision: d } : {}), - screen: stop === 'a window opened' ? screen() : undefined, - }; - }; - - window.__mcp = { newGame, loadSave, exportSave, status, network, city, find, trace, peering, hotSpots, run, click, panel, openLink, actions, advance, screen, - schema, catalog, state, results, ui, classes }; -})(); diff --git a/scripts/lib/page.js b/scripts/lib/page.js index 880af5c..b905f26 100644 --- a/scripts/lib/page.js +++ b/scripts/lib/page.js @@ -3,8 +3,14 @@ // The result is the same single, self-contained index.html the game has always shipped: one request, // no module loader, no runtime cost. See docs/ARCHITECTURE.md ("Source layout") and docs/adr/. // +// A line `` is the same, but only in the development page (dev: true): the +// tools' side of the game (src/agent/, the agent facade the MCP server drives) for npm run dev, the +// MCP server's own page and the tests that ask for it. Everywhere else the line is dropped whole, so +// the page players get is exactly what it would be without it (docs/adr/0004-dev-only-code.md). +// // node scripts/lib/page.js [-o FILE] the page as it ships (stdout by default) -// node scripts/lib/page.js --source [-o FILE] assembled only, labels as in src/ (what tests and npm run dev use) +// node scripts/lib/page.js --source [-o FILE] assembled only, labels as in src/ (what tests use) +// node scripts/lib/page.js --source --dev [-o FILE] the development page: with src/agent/ (what npm run dev serves) // node scripts/lib/page.js --ref origin/main -o FILE the page as it ships at a git ref // // --ref uses that commit's own assembler, so it keeps working when this file changes; refs from before @@ -15,7 +21,7 @@ const path = require('node:path'); const { execFileSync } = require('node:child_process'); const ROOT = path.join(__dirname, '..', '..'); -const INCLUDE = /^$/; +const INCLUDE = /^$/; // Every file under dir, as paths relative to dir with '/' separators, in a stable order // (plain code-unit comparison, so the order never depends on the machine's locale). @@ -45,7 +51,8 @@ function partials(src, dir) { } // The assembled page as a string, plus a map of which output line came from which source file. -function assemble({ src = path.join(ROOT, 'src') } = {}) { +// dev: also the @include-dev parts (the development page); without it, their lines are left out entirely. +function assemble({ src = path.join(ROOT, 'src'), dev = false } = {}) { const shell = fs.readFileSync(path.join(src, 'index.html'), 'utf8'); const out = [], map = []; let line = 1; @@ -57,7 +64,8 @@ function assemble({ src = path.join(ROOT, 'src') } = {}) { line++; return; } - for (const p of partials(src, m[1])) { + if (m[1] && !dev) return; + for (const p of partials(src, m[2])) { const n = p.text.split('\n').length - 1; map.push({ file: p.file, from: line, to: line + n - 1 }); out.push(p.text); @@ -104,7 +112,7 @@ module.exports = { assemble, assembleRef, shipped, pageFile, locate, listFiles, if (require.main === module) { const args = process.argv.slice(2); const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : null; }; - const html = opt('--ref') ? assembleRef(opt('--ref')) : args.includes('--source') ? assemble().html : shipped().html; + const html = opt('--ref') ? assembleRef(opt('--ref')) : args.includes('--source') ? assemble({ dev: args.includes('--dev') }).html : shipped().html; const out = opt('-o'); if (out) { fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true }); fs.writeFileSync(out, html); } else process.stdout.write(html); diff --git a/src/agent/10-domains.js b/src/agent/10-domains.js new file mode 100644 index 0000000..bdbb762 --- /dev/null +++ b/src/agent/10-domains.js @@ -0,0 +1,104 @@ +/* ================= AGENT API: argument domains ================= + The agent facade (window.TUBES, this folder) is how tools play the game: the MCP server (scripts/mcp.js) calls it in + its own jsdom page. It is part of the development page only (): the page players get has + none of it, so nothing in src/game/ may name anything defined here. Nothing here runs until a tool calls it: these + files only define tables and functions. + A domain is what an argument may be: an id in a catalog table, a key, an index, a small fixed list, or a check. */ +const API_DOMAINS={ + // Tables from the catalog: an id in a list, a key in an object, or an index into a list. + cityId:{table:'CITIES',kind:'id'}, + netId:{table:'NETS',kind:'id'}, + cableId:{table:'CABLES',kind:'id'}, + fabId:{table:'FAB',kind:'key'}, + opticId:{table:'OPT',kind:'key'}, + systemId:{table:'DF_SYS',kind:'key'}, + designId:{table:'SEA_DESIGNS',kind:'key'}, + upgradeId:{table:'SUB_UPGRADES',kind:'key'}, + bizTypeId:{table:'BIZ_T',kind:'key'}, + portTier:{table:'PORT',kind:'index'}, + linkTier:{table:'LT',kind:'index'}, + nniTier:{table:'NNI',kind:'index'}, + vxcTier:{table:'VXC',kind:'index'}, + routerModel:{table:'RG',kind:'index'}, + scrubTier:{table:'SCRUB_TIERS',kind:'index'}, + // Small fixed vocabularies the game itself checks by list membership. + // The link metric presets, plus "custom" for a hand-tuned number (ACT.setMetric). + metric:{kind:'enum',values:()=>[...Object.keys(MET),'custom']}, + egress:{table:'PREF',kind:'key'}, + routeMode:{table:'RT',kind:'key'}, + site:{kind:'enum',values:['a','b','ab']}, + step:{kind:'enum',values:[1,-1]}, + connKind:{kind:'enum',values:['t','p','ix','c','nni']}, + egressKind:{kind:'enum',values:['t','p','ix','c','nni','l2']}, + peerPolicy:{table:'PPOL',kind:'enum'}, + // The intern, their orders and the new-POP template (opsHire, opsToggle, opsParam…). + internId:{table:'INTERNS',kind:'key'}, + opsKey:{table:'OPSK',kind:'key'}, + opsPopKind:{kind:'enum',values:()=>OPS_POP.slice()}, + opsTplKey:{kind:'enum',values:()=>OPS_TPL.slice()}, + // The specialist's offers: a seat on a consortium cable, the charter, a vendor demo. + seatPairs:{kind:'enum',values:()=>SEAT_N.slice()}, + charterKey:{table:'CHARTERS',kind:'key'}, + // The link metric editor: a factor or an exact weight (metricMode, metricSet). + metricKind:{kind:'enum',values:['f','w']}, + // The NOC's auto-mitigation switches (ddosAuto). + ddosKey:{kind:'enum',values:['rtbh','scrub']}, + // Puzzle and architect builds: the tiers a puzzle may light, the router models it offers. + pztTier:{kind:'fn',ok:v=>PZ_TIERS.includes(+v)||AR_TIERS.includes(+v)}, + pzRouterModel:{table:'PZ_RG',kind:'index'}, + pzRouteMode:{kind:'enum',values:['normal','fast']}, + // The bulk PNI order takes one network or null for every network at every shared POP (ACT.pniAll). + pniAllNet:{kind:'fn',ok:v=>v===null||(typeof v==='string'&&!!NET[v])}, + dashTab:{kind:'enum',values:()=>DTABS.slice()}, + dashSortKey:{kind:'enum',values:['name','asn','type','traffic','cost','lost']}, + leftTab:{kind:'enum',values:['goals','deals','noc','nets']}, + netFilter:{kind:'enum',values:['all','out']}, + pniFilter:{kind:'enum',values:['all','t','worth','pni']}, + listPage:{kind:'enum',values:['conn','cust','nets','pni']}, + custSortKey:{kind:'enum',values:['mood','mo','name','city']}, + connFilter:{kind:'enum',values:['all','k']}, + connSortKey:{kind:'enum',values:['k','city','name','use','mo']}, + dfSource:{kind:'enum',values:['lease','build','cable']}, + cityIdArray:{kind:'array',of:'cityId'}, + // Anything a panel can reach: an exchange city, a rival exchange id, one of your own exchanges. + ixId:{kind:'fn',ok:v=>isIx(v)}, + // A PNI also takes tier:-1, the 1G courtesy port a network may offer (ACT.pni). + pniTier:{kind:'fn',ok:v=>v===-1||(Number.isInteger(v)&&v>=0&&vtypeof v==='string'&&upcomingConfs(75).some(c=>c.key===v)}, + // traceroute goes to your own POPs and to networks; traceModal parses a net:/city: prefix. + traceTo:{kind:'fn',ok:v=>typeof v==='string'&&(NET[v]||isCity(v))}, + // Entity ids (uid()) cannot be validated against a table: shape only. A wrong id is the game's + // to answer, honestly, with no_effect — never a refusal invented on this side of the wall. + entityId:{kind:'string'}, + scnId:{table:'SCN',kind:'id'}, + // A traceroute target in the modal's own terms. +}; + +/* Type names an arg can take instead of a domain: 'string' | 'boolean' | 'integer'. */ + +function apiDomCheck(dom,v){ + const d=API_DOMAINS[dom]; + // The game's own buttons ship truthiness as 0 and 1 (custOpen's {"sad":0}); accept the game's dialect. + if(dom==='boolean')return {ok:v===true||v===false||v===0||v===1}; + if(!d)return {ok:dom==='integer'?Number.isInteger(v):typeof v===dom}; // 'string' | 'integer' + if(d.kind==='array')return {ok:Array.isArray(v)&&v.every(x=>apiDomCheck(d.of,x).ok)}; + const t=d.table?API_CATALOG_TABLE(d.table):null; + if(d.kind==='id')return {ok:!!t&&t.some(x=>x&&x.id===v)}; + if(d.kind==='string')return {ok:typeof v==='string'}; + if(d.kind==='key'||d.kind==='enum'){ + const vs=d.kind==='key'?Object.keys(t||{}):(t||(typeof d.values==='function'?d.values():d.values)||[]); + return {ok:vs.includes(v)};} + if(d.kind==='index')return {ok:Number.isInteger(v)&&v>=0&&v<(t?t.length:0)}; + return {ok:!!d.ok&&d.ok(v)}; +} +function apiDomValues(dom){ + const d=API_DOMAINS[dom];if(!d)return null; + const t=d.table?API_CATALOG_TABLE(d.table):null; + if(d.kind==='array')return {of:d.of}; + if(d.kind==='id')return t?t.map(x=>x.id):[]; + if(d.kind==='key')return t?Object.keys(t):[]; + if(d.kind==='enum')return t||(typeof d.values==='function'?d.values():d.values)||[]; + if(d.kind==='index')return {from:0,to:(t?t.length:1)-1}; + return null; +} diff --git a/scripts/lib/mcp-commands.js b/src/agent/20-commands.js similarity index 66% rename from scripts/lib/mcp-commands.js rename to src/agent/20-commands.js index eac4c1d..2669c80 100644 --- a/scripts/lib/mcp-commands.js +++ b/src/agent/20-commands.js @@ -1,115 +1,13 @@ -// Runs inside the game page before scripts/lib/mcp-page.js, in the game's own global scope: the typed command -// tables the MCP server's act tool dispatches through. Data and small helpers only, no state. -// -// Every action in ACT is in exactly one class (tests/mcp-commands.test.js fails otherwise, so a new action forces a -// decision): CMD, a game command with typed arguments; VIEW, which changes only what is on screen; BOUND, which only -// drafts an input another command reads; SESSION, which starts, retries or leaves a game or dismisses a coaching -// screen; or the server's DENY list (scripts/lib/mcp-page.js). CMD fields: args [name, domain|'string'|'boolean'|'integer', required]; bind(args) writes the UI -// a panel would set (bindsUI: the UI keys it touches, restored after a dry run); open/dom: the window an input lives -// in and the fields that must exist before dispatch; pass(args) reshapes the args for the action (confirmations); -// confirm 'arg' (passed through) or 'double' (the game arms a button first); decides (may end in a question); reads -// 'modal' (the window's text is the report); watch (extra fingerprint paths, #name filled from args); quote (the dry -// run, priced with the game's own helpers); doc. -window.__mcpCmds = (() => { -const API_DOMAINS={ - // Tables from the catalog: an id in a list, a key in an object, or an index into a list. - cityId:{table:'CITIES',kind:'id'}, - netId:{table:'NETS',kind:'id'}, - cableId:{table:'CABLES',kind:'id'}, - fabId:{table:'FAB',kind:'key'}, - opticId:{table:'OPT',kind:'key'}, - systemId:{table:'DF_SYS',kind:'key'}, - designId:{table:'SEA_DESIGNS',kind:'key'}, - upgradeId:{table:'SUB_UPGRADES',kind:'key'}, - bizTypeId:{table:'BIZ_T',kind:'key'}, - portTier:{table:'PORT',kind:'index'}, - linkTier:{table:'LT',kind:'index'}, - nniTier:{table:'NNI',kind:'index'}, - vxcTier:{table:'VXC',kind:'index'}, - routerModel:{table:'RG',kind:'index'}, - scrubTier:{table:'SCRUB_TIERS',kind:'index'}, - // Small fixed vocabularies the game itself checks by list membership. - // The link metric presets, plus "custom" for a hand-tuned number (ACT.setMetric). - metric:{kind:'enum',values:()=>[...Object.keys(MET),'custom']}, - egress:{table:'PREF',kind:'key'}, - routeMode:{table:'RT',kind:'key'}, - site:{kind:'enum',values:['a','b','ab']}, - step:{kind:'enum',values:[1,-1]}, - connKind:{kind:'enum',values:['t','p','ix','c','nni']}, - egressKind:{kind:'enum',values:['t','p','ix','c','nni','l2']}, - peerPolicy:{table:'PPOL',kind:'enum'}, - // The intern, their orders and the new-POP template (opsHire, opsToggle, opsParam…). - internId:{table:'INTERNS',kind:'key'}, - opsKey:{table:'OPSK',kind:'key'}, - opsPopKind:{kind:'enum',values:()=>OPS_POP.slice()}, - opsTplKey:{kind:'enum',values:()=>OPS_TPL.slice()}, - // The specialist's offers: a seat on a consortium cable, the charter, a vendor demo. - seatPairs:{kind:'enum',values:()=>SEAT_N.slice()}, - charterKey:{table:'CHARTERS',kind:'key'}, - // The link metric editor: a factor or an exact weight (metricMode, metricSet). - metricKind:{kind:'enum',values:['f','w']}, - // The NOC's auto-mitigation switches (ddosAuto). - ddosKey:{kind:'enum',values:['rtbh','scrub']}, - // Puzzle and architect builds: the tiers a puzzle may light, the router models it offers. - pztTier:{kind:'fn',ok:v=>PZ_TIERS.includes(+v)||AR_TIERS.includes(+v)}, - pzRouterModel:{table:'PZ_RG',kind:'index'}, - pzRouteMode:{kind:'enum',values:['normal','fast']}, - // The bulk PNI order takes one network or null for every network at every shared POP (ACT.pniAll). - pniAllNet:{kind:'fn',ok:v=>v===null||(typeof v==='string'&&!!NET[v])}, - dashTab:{kind:'enum',values:()=>DTABS.slice()}, - dashSortKey:{kind:'enum',values:['name','asn','type','traffic','cost','lost']}, - leftTab:{kind:'enum',values:['goals','deals','noc','nets']}, - netFilter:{kind:'enum',values:['all','out']}, - pniFilter:{kind:'enum',values:['all','t','worth','pni']}, - listPage:{kind:'enum',values:['conn','cust','nets','pni']}, - custSortKey:{kind:'enum',values:['mood','mo','name','city']}, - connFilter:{kind:'enum',values:['all','k']}, - connSortKey:{kind:'enum',values:['k','city','name','use','mo']}, - dfSource:{kind:'enum',values:['lease','build','cable']}, - cityIdArray:{kind:'array',of:'cityId'}, - // Anything a panel can reach: an exchange city, a rival exchange id, one of your own exchanges. - ixId:{kind:'fn',ok:v=>isIx(v)}, - // A PNI also takes tier:-1, the 1G courtesy port a network may offer (ACT.pni). - pniTier:{kind:'fn',ok:v=>v===-1||(Number.isInteger(v)&&v>=0&&vtypeof v==='string'&&upcomingConfs(75).some(c=>c.key===v)}, - // traceroute goes to your own POPs and to networks; traceModal parses a net:/city: prefix. - traceTo:{kind:'fn',ok:v=>typeof v==='string'&&(NET[v]||isCity(v))}, - // Entity ids (uid()) cannot be validated against a table: shape only. A wrong id is the game's - // to answer, honestly, with no_effect — never a refusal invented on this side of the wall. - entityId:{kind:'string'}, - scnId:{table:'SCN',kind:'id'}, - // A traceroute target in the modal's own terms. -}; - -/* Type names an arg can take instead of a domain: 'string' | 'boolean' | 'integer'. */ - -function apiDomCheck(dom,v){ - const d=API_DOMAINS[dom]; - // The game's own buttons ship truthiness as 0 and 1 (custOpen's {"sad":0}); accept the game's dialect. - if(dom==='boolean')return {ok:v===true||v===false||v===0||v===1}; - if(!d)return {ok:dom==='integer'?Number.isInteger(v):typeof v===dom}; // 'string' | 'integer' - if(d.kind==='array')return {ok:Array.isArray(v)&&v.every(x=>apiDomCheck(d.of,x).ok)}; - const t=d.table?API_CATALOG_TABLE(d.table):null; - if(d.kind==='id')return {ok:!!t&&t.some(x=>x&&x.id===v)}; - if(d.kind==='string')return {ok:typeof v==='string'}; - if(d.kind==='key'||d.kind==='enum'){ - const vs=d.kind==='key'?Object.keys(t||{}):(t||(typeof d.values==='function'?d.values():d.values)||[]); - return {ok:vs.includes(v)};} - if(d.kind==='index')return {ok:Number.isInteger(v)&&v>=0&&v<(t?t.length:0)}; - return {ok:!!d.ok&&d.ok(v)}; -} -function apiDomValues(dom){ - const d=API_DOMAINS[dom];if(!d)return null; - const t=d.table?API_CATALOG_TABLE(d.table):null; - if(d.kind==='array')return {of:d.of}; - if(d.kind==='id')return t?t.map(x=>x.id):[]; - if(d.kind==='key')return t?Object.keys(t):[]; - if(d.kind==='enum')return t||(typeof d.values==='function'?d.values():d.values)||[]; - if(d.kind==='index')return {from:0,to:(t?t.length:1)-1}; - return null; -} - +/* ================= AGENT API: the command tables ================= + Every action in ACT is in exactly one class (tests/mcp-commands.test.js fails otherwise, so a new action forces a + decision): API_CMD, a game command with typed arguments; API_VIEW, which changes only what is on screen; API_BOUND, + which only drafts an input another command reads; API_SESSION, which starts, retries or leaves a game or dismisses a + coaching screen; or API_DENY, never run by a tool. CMD fields: args [name, domain|'string'|'boolean'|'integer', + required]; bind(args) writes the UI a panel would set (bindsUI: the UI keys it touches, restored after a dry run); + open/dom: the window an input lives in and the fields that must exist before dispatch; pass(args) reshapes the args + for the action (confirmations); confirm 'arg' (passed through) or 'double' (the game arms a button first); decides + (may end in a question); reads 'modal' (the window's text is the report); watch (extra fingerprint paths, #name + filled from args); quote (the dry run, priced with the game's own helpers); doc. */ const API_CMD={ /* ---------- footprint: buildings, routers, POPs ---------- */ buildPop:{args:[['city','cityId']], @@ -611,7 +509,8 @@ const API_BOUND={ }; /* Starting, retrying and leaving scenarios, puzzles and architect runs, and the screens a player dismisses. They run - as their buttons run them; new_game, load_save and export_save are the other half of the session (mcp-page.js). */ + as their buttons run them; new_game, load_save and export_save are the other half of the session, and exist only in + the MCP server's own page (scripts/lib/mcp-headless.js). */ const API_SESSION={ startScn:{args:[['id','scnId']],doc:'Start a scenario (ids from catalog SCN), replacing the current game.'}, startWeekly:{args:[],doc:'Start this week\'s weekly scenario, replacing the current game. The week follows the real date.'}, @@ -625,199 +524,18 @@ const API_SESSION={ tutSkip:{args:[],doc:'Skip the tutorial coaching.'}, }; -const API_STATE_DOC={ - v:{type:'integer',doc:'Save format version.'}, - name:{type:'string',doc:'Your network\'s name.'}, - asn:{type:'integer',doc:'Your AS number.'}, - home:{type:'string',doc:'The city you started in.'}, - day:{type:'integer',doc:'Days since the company was founded.'}, - cash:{type:'number',doc:'Cash on hand. Goes negative into the red; -100k is bankruptcy.'}, - priceMul:{type:'number',doc:'Multiplier on transit prices (weekly modifier).'}, - mode:{type:'string',doc:'normal | sandbox | scenario | puzzle.'}, - rules:{type:'map',doc:'The rules this network locked in at its door: preset (soft, freeze, oncall, bgp, sandbox or puzzle), the chaos dial, lead times, the market, and the Best Effort extras (sea, confs, broke, moods, pnis), which are only written where they differ from the classic game. They stay for the network\'s whole life.'}, - charter:{type:'string',doc:'The charter picked in the first month of a normal game: global | boutique.'}, - chartSet:{type:'boolean',doc:'The charter has been picked; false while the choice is still open.'}, - solWon:{type:'integer',doc:'The day the Speed of Light win landed (boutique charter), or 0.'}, - lvl:{type:'integer',doc:'Customer level (unlocks customer types).'}, - ltv:{type:'integer',doc:'Level at which Tier 1 vendors were visible (title-screen pick).'}, - t1v:{type:'integer',doc:'Level at which Tier 1 transit was offered.'}, - auV:{type:'integer',doc:'Australia content level gate.'}, - seen:{type:'array',doc:'Network ids the deals panel has already shown. Vestigial: written by newGame, read nowhere.'}, - pops:{type:'map',doc:'Your POPs by city id: day opened, broadband (bb), ad boost, downtime, routers, generator, second site.'}, - links:{type:'array',doc:'Your links: waves, dark fiber (df), own cables and fabric circuits (vxc), each with an entity id.'}, - transit:{type:'array',doc:'Transit ports: city, net, tier, LAG members, port history for 95th-percentile billing.'}, - ixp:{type:'map',doc:'IX ports by exchange city; tier per port (may exceed 1 with LAG members in ixn).'}, - rs:{type:'map',doc:'Route-server sessions by exchange city.'}, - ixn:{type:'map',doc:'LAG members on IX ports by exchange city.'}, - ixSite:{type:'map',doc:'Which building each IX port sits in (a, b or ab).'}, - ixPref:{type:'map',doc:'Egress preference per IX port.'}, - myIx:{type:'map',doc:'Exchanges you founded: name, members, join schedule, fabric step.'}, - peers:{type:'map',doc:'Peering sessions, keyed "net@ix".'}, - pairMet:{type:'map',doc:'Routing metric per city pair (prefer/avoid/backup/normal), keyed by pair.'}, - pni:{type:'array',doc:'Private interconnects: city, net, tier, ready day, augments (up), LAG, sacrificial flag.'}, - caches:{type:'array',doc:'CDN cache boxes: city, net, building.'}, - nni:{type:'array',doc:'Fabric ports: city, provider, tier.'}, - biz:{type:'array',doc:'Signed customers: type, cities, bandwidth, rate, mood, contract dates.'}, - offers:{type:'array',doc:'Pending customer offers, each expiring on a day.'}, - done:{type:'map',doc:'Goals landed, by goal id → day.'}, - ach:{type:'map',doc:'Badges earned this game, by badge id → day.'}, - inc:{type:'array',doc:'Open incidents: type, what they hit, until when, optional rush-repair price.'}, - ddosStarts:{type:'array',doc:'The days the attacks of the last week started; at most 14 a week.'}, - ev:{type:'map',doc:'Live world events: the running DDoS, route leaks, fabric failures, price shocks.'}, - stats:{type:'map',doc:'Counters: incidents survived, loans taken, sharks, conferences attended, peak traffic…'}, - log:{type:'array',doc:'The NOC notification feed, newest first, capped at 60; identical notices within a minute fold with a count.'}, - nextFail:{type:'integer',doc:'The day the next failure fires.'}, - nextEvent:{type:'integer',doc:'The day the next world event fires.'}, - rng:{type:'integer',doc:'The scenario seed; it predicts every future random draw.'}, - usedNames:{type:'array',doc:'Customer names already handed out.'}, - spares:{type:'map',doc:'Spare optics on the shelf, by optic id.'}, - scrubs:{type:'array',doc:'Scrubbing centres: city and tier.'}, - scrubMode:{type:'string',doc:'always | ondemand.'}, - cnLic:{type:'map',doc:'Mainland China licence: none | pending (with ready day) | ok.'}, - ppol:{type:'string',doc:'Your published peering policy: open | selective | closed.'}, - pdesk:{type:'map',doc:'This week\'s peering desk summary: sessions accepted and declined at which exchanges.'}, - pdeskRep:{type:'map',doc:'Last week\'s peering desk summary, as the NOC log reported it.'}, - ops:{type:'map',doc:'The NOC intern: who is hired, each standing order\'s on/off switch and settings, the monthly budget and what it spent, per-POP exceptions, the new-POP template and the weekly log.'}, - core:{type:'map',doc:'Your backbone technology: lv bought, the level it runs at, the interop lab.'}, - ddosAuto:{type:'map',doc:'The NOC\'s auto-mitigation switches: rtbh and scrub.'}, - popStd:{type:'map',doc:'The standard POP: router model and count new POPs start with, or null for none.'}, - demo:{type:'map',doc:'Vendor demo units on order, by "kind:id" → ready day.'}, - seatOff:{type:'map',doc:'The pending consortium-cable seat offer: landings, km, name, expiry day.'}, - monkey:{type:'map',doc:'The chaos monkey: next visit day, whether it is in your network now, days left, whether anyone noticed.'}, - fleet:{type:'map',doc:'Cable-ship voyages by ship id: the cut it sails to, when it arrives, splices and comes home.'}, - achP:{type:'map',doc:'Which rule set each badge was earned under (oncall, freeze, bgp), by badge id.'}, - calV:{type:'integer',doc:'Calendar save-format marker: 1 once the real calendar (28-31-day months) applies.'}, - pz:{type:'map',doc:'The running puzzle: its id, cities, flows to deliver, budget and stars.'}, - ar:{type:'map',doc:'The running architect run: its HQ, brief index, gold sites, spend and the build it started from.'}, - loans:{type:'array',doc:'Active loans: bank, balance, APR, term, share (equity banks).'}, - loanOffers:{type:'array',doc:'Pending loan offers.'}, - loanStrikes:{type:'integer',doc:'How many loan offers you have let lapse.'}, - confReg:{type:'map',doc:'Conferences registered for, by key; "sp" when sponsoring.'}, - hw:{type:'map',doc:'Hardware market: price shocks and any price lock.'}, - capDeal:{type:'map',doc:'The pending capacity deal from a capacity conference.'}, - cam:{type:'map',doc:'Map camera position. View state that save() happens to store inside S.'}, - uiSpeed:{type:'number',doc:'The speed you left the game at. View state that save() stores inside S.'}, - won:{type:'boolean',doc:'You reached Tier 1.'}, - t1Now:{type:'boolean',doc:'Tier 1 right now, as of the last day; falling out of it is announced.'}, - lost:{type:'boolean',doc:'The bank repossessed the routers.'}, - neg:{type:'integer',doc:'Days in the red in a row.'}, - hist:{type:'array',doc:'Daily history for the graphs: demand, served, exit split, revenue, cost, cash.'}, - scn:{type:'map',doc:'The running scenario: id, rules, day limit, done/failed, and the day of the next scripted attack (nextDdos).'}, - dk:{type:'map',doc:'De-Kicks state: per-exchange multipliers, add-ons, retention, the live quote (q) and the remembered one (lastQ).'}, - grace:{type:'map',doc:'Courtesy transit after a merger wave, until a day.'}, - merged:{type:'map',doc:'Networks merged into others this game.'}, - tut:{type:'map',doc:'Tutorial progress.'}, - conf:{type:'map',doc:'The conference glow: region and until when; sp when you sponsored.'}, - phpDone:{type:'boolean',doc:'One-shot flag.'}, - krExit:{type:'map',doc:'Korea exit state.'}, - auNews:{type:'boolean',doc:'One-shot flag: the Australia news toast.'}, - richTold:{type:'boolean',doc:'One-shot flag: the cash milestone toast.'}, +/* Actions no tool runs, by reason: files, storage slots, settings and the title screen are not the game's, and time + moves only through advance (or the page's own clock). */ +const API_WHY={ + time:'use advance to move time',start:'use new_game',files:'use load_save or export_save', + slots:'saved networks in browser storage are not part of this game',prefs:'device and player settings are not part of the game', + browser:'it needs the browser itself (a share sheet, the clipboard, an install prompt or a reload)', }; - -const API_RESULTS_DOC={ - nt:{type:'map',doc:'Traffic per network through transit, by net id.'}, - tNet:{type:'map',doc:'Traffic per network you hand to each upstream, by "net@upstream".'}, - reachNT:{type:'number',doc:'Networks reachable without transit.'}, - teBlack:{type:'number',doc:'Traffic blackholed by RouteScript rules.'}, - teMoved:{type:'number',doc:'Traffic Auto-TE spilled onto alternate paths.'}, - egT:{type:'map',doc:'Egress split by exit kind (c/p/ix/t/l2) in Gbps.'}, - egDesc:{type:'map',doc:'RouteScript drains per exit.'}, - netEg:{type:'map',doc:'Per-network egress split: which exit carries which network.'}, - ef:{type:'map',doc:'LAZY per-link exit breakdown: what crosses each link, per network, built only when a panel asks. What is in here depends on which panels have rendered.'}, - l2:{type:'map',doc:'Layer-2 traffic per customer (L2VPN, SD-WAN, waves).'}, - l2lat:{type:'map',doc:'Latency per L2 customer.'}, - l2route:{type:'map',doc:'Which path an L2 customer\'s traffic takes.'}, - l2split:{type:'map',doc:'L2 traffic split per path.'}, - nodeLoad:{type:'map',doc:'Router forwarding load per city.'}, - nodeCap:{type:'map',doc:'Router forwarding capacity per city.'}, - div:{type:'map',doc:'Traffic diversity per customer (how split their paths are).'}, - gfwLost:{type:'number',doc:'Traffic lost to the Great Firewall.'}, - gfwCross:{type:'number',doc:'Traffic crossing into mainland China.'}, - p95:{type:'map',doc:'95th-percentile transit readings per port.'}, - peered:{type:'number',doc:'Share of traffic that stays on peering.'}, - peerShare:{type:'number',doc:'Fraction of traffic served by peers (mood driver).'}, - load:{type:'map',doc:'Load per link in Gbps.'}, - useT:{type:'map',doc:'Transit use per port id.'}, - useIx:{type:'map',doc:'IX use per exchange city.'}, - usePni:{type:'map',doc:'PNI use per port id.'}, - useCache:{type:'map',doc:'Cache use per box id.'}, - cityDem:{type:'map',doc:'Eyeball + customer demand per city.'}, - citySrv:{type:'map',doc:'Traffic served per city.'}, - cityEye:{type:'map',doc:'Eyeballs online per city.'}, - latF:{type:'map',doc:'Fraction of each city\'s traffic that goes far (over a threshold latency).'}, - latFar:{type:'map',doc:'The far exit each slow city sends traffic through.'}, - demTo:{type:'map',doc:'Your traffic destined to each network, in Gbps. The number CDN caches ask about.'}, - served:{type:'number',doc:'Total traffic served, in Gbps.'}, - demand:{type:'number',doc:'Total traffic demanded, in Gbps.'}, - reach:{type:'number',doc:'Fraction of the internet you can reach (0..1).'}, - sessions:{type:'number',doc:'Peering sessions up.'}, - revMo:{type:'number',doc:'Revenue per month.'}, - costMo:{type:'number',doc:'Cost per month.'}, - cost:{type:'map',doc:'Monthly cost by category (transit, pni, ix, links…).'}, - rev:{type:'map',doc:'Monthly revenue by source.'}, - reachable:{type:'map',doc:'Networks reachable per net id.'}, - cone:{type:'map',doc:'Which peer\'s customer cone carries each network you reach without transit of your own, by net id.'}, - ddos:{type:'array',doc:'Per live attack: the target, its size, which ports it fills, what Flowspec and each scrubbing centre cleaned, and what reaches the target.'}, - haul:{type:'array',doc:'Scrubbing detours: from the attacked city to each centre, one-way latency and how much they carry.'}, - tgtF:{type:'map',doc:'The share of a targeted customer\'s traffic that survives the attack, by customer id.'}, - bbF:{type:'map',doc:'The share of a city\'s broadband subscribers that survive an attack on them, by city id.'}, - fsUse:{type:'map',doc:'Flowspec rules in use per city: used of the routers\' rule capacity.'}, - bizDem:{type:'map',doc:'Business customers\' share of each city\'s demand, in Gbps (what RouteScript\'s protect customers serves first).'}, - bizSrv:{type:'map',doc:'Of that business demand, what was served, per city.'}, - graceNets:{type:'number',doc:'Networks reached over the courtesy route after a merger wave.'}, - cityBlocked:{type:'map',doc:'Set up per city by the traffic computation; nothing fills it at present.'}, - ddosHot:{type:'map',doc:'Cities whose ports a flood is filling, for the map\'s pulse. Keyed by city id.'}, +const API_DENY={ + speed:'time',phonePlay:'time',phoneSpeed:'time', + start:'start',newgame:'start',cont:'start',toTitle:'start',resetAsk:'start', + exportSave:'files',importGo:'files',importPick:'files',slotExport:'files', + slotBack:'slots',slotDel:'slots',slotDelGo:'slots',slotMenu:'slots',slotRetry:'slots',slotSpace:'slots',slotSwitch:'slots',slotTake:'slots', + animSet:'prefs',langSet:'prefs',menu:'prefs',mute:'prefs',prefSet:'prefs',settings:'prefs',settingsClose:'prefs',soundSet:'prefs',vpSet:'prefs', + install:'browser',share:'browser',shareDl:'browser',shareGo:'browser',traceCopy:'browser',updateLater:'browser',updateNow:'browser',wsShare:'browser',pzShare:'browser', }; - -/* One arg of a spec as the schema states it: the domain when there is one (catalog() resolves - it), the bare type otherwise, and the concrete value list or range where it is fixed. */ -function apiArgSpec([name,dom,req]){ - const a={name,required:req!==false}; - if(API_DOMAINS[dom])a.domain=dom;else a.type=dom; - const v=apiDomValues(dom); - if(Array.isArray(v))a.values=v;else if(v&&v.from!==undefined)a.range=v; - return a;} - -/* Dotted subtrees, no wildcards. An array walks by index (`biz.3`) or by entity id (`links[#id]`). */ -function apiPath(o,p){ - if(p===undefined||p===null||p==='')return o; - let v=o; - for(const k of String(p).split('.')){ - if(v==null)return undefined; - if(Array.isArray(v)){const i=Number(k); - v=(Number.isInteger(i)&&String(i)===k&&i>=0&&ix&&typeof x==='object'&&x.id===k);} - else if(v instanceof Set)v=[...v]; - else if(v instanceof Map)v=Object.fromEntries(v); - else if(typeof v==='object')v=v[k]; - else return undefined;} - return v;} - -function apiJson(v){ - if(v instanceof Set)return [...v].map(apiJson); - if(v instanceof Map)return apiJson(Object.fromEntries(v)); - if(v&&typeof v==='object')return Array.isArray(v)?v.map(apiJson):Object.fromEntries(Object.entries(v).map(([k,x])=>[k,apiJson(x)])); - if(typeof v==='function')return undefined; - return v;} - -/* The tables the argument domains point at. Everything is a static reference except three, - each computed for a reason: BADGES hides unearned secrets like the badge wall; conferences - carries the keys confGo/confSponsor need, which exist in no field of S; TE_RECIPES renders - each recipe's script, because the source is a function and some read the live network. The - recipes' relevance score is not exposed: judging which one fits is the agent's job. */ -const API_TABLES={CITIES,NETS,CABLES,XIX,PORT,LT,NNI,VXC,RG,OPT,DF_SYS,FAB,SCRUB_TIERS,BIZ_T,LEVELS,GOALS,SCN,BANKS,REQS,NSH,MET,PREF,RT,PPOL,CONFS,LAG_MAX,RMAX,REGEN_MAX,START_CASH,CONF_COST,CONF_SP,CAP_COST,CAP_LV,CONF_DAYS,SUB_UPGRADES,SEA_DESIGNS,TE_COST,TE_MO,MYIX_COST,CN_LIC,SITE2_COST,MYIX_FAB,INTERNS,OPSK,CHARTERS,SEAT_N,CORE_LV,CORE_COST,CORE_REQ,CORE_LAB,INTERN_MO,PZ_TIERS,AR_TIERS,PZ_RG}; -const API_MADE={ - BADGES:()=>!S?[]:BADGES.map(b=>{const on=S.ach&&S.ach[b.id]!==undefined,ever=!!hof()[b.id]; - return b.secret&&!on&&!ever?{id:b.id,i:'❔',t:'???',d:tr('badges.a_secret_badge'),r:b.r,secret:true}:{...b,ever};}), - conferences:()=>!S?[]:upcomingConfs(75).map(cf=>({key:cf.key,name:cf.n,city:cf.c,day:cf.day,capacity:!!cf.cap,cost:confCost(cf),sponsorCost:confSp(cf)?CONF_SP:null})), - TE_RECIPES:()=>!S?[]:TE_RECIPES.map(r=>({id:r.id,name:tr(r.n),description:tr(r.d),script:r.src().join('\n')})), -}; -function API_CATALOG_TABLE(name){return name in API_MADE?API_MADE[name]():API_TABLES[name];} - -/* UI minus the render caches and pointer scratch, which are inputs to nothing. - Everything a command binds (pending, route, via, dfSrc, dfSys, seaDesign, cnPrem, decom, - teDraft, confirm) stays, so an agent can see what it was given. */ -const API_UI_HIDDEN={_lh:1,_ph:1,_tb:1,_layer:1,layerAt:1,hover:1,drag:1,snap:1}; - -return {API_DOMAINS,API_CMD,API_VIEW,API_BOUND,API_SESSION,API_STATE_DOC,API_RESULTS_DOC,API_TABLES,API_MADE,API_UI_HIDDEN, - apiDomCheck,apiDomValues,apiArgSpec,apiPath,apiJson}; -})(); diff --git a/src/agent/30-docs.js b/src/agent/30-docs.js new file mode 100644 index 0000000..3849db2 --- /dev/null +++ b/src/agent/30-docs.js @@ -0,0 +1,145 @@ +/* ================= AGENT API: what the state and the results hold ================= + One line per field of S and of R (tests/mcp-commands.test.js fails on a field without one). */ +const API_STATE_DOC={ + v:{type:'integer',doc:'Save format version.'}, + name:{type:'string',doc:'Your network\'s name.'}, + asn:{type:'integer',doc:'Your AS number.'}, + home:{type:'string',doc:'The city you started in.'}, + day:{type:'integer',doc:'Days since the company was founded.'}, + cash:{type:'number',doc:'Cash on hand. Goes negative into the red; -100k is bankruptcy.'}, + priceMul:{type:'number',doc:'Multiplier on transit prices (weekly modifier).'}, + mode:{type:'string',doc:'normal | sandbox | scenario | puzzle.'}, + rules:{type:'map',doc:'The rules this network locked in at its door: preset (soft, freeze, oncall, bgp, sandbox or puzzle), the chaos dial, lead times, the market, and the Best Effort extras (sea, confs, broke, moods, pnis), which are only written where they differ from the classic game. They stay for the network\'s whole life.'}, + charter:{type:'string',doc:'The charter picked in the first month of a normal game: global | boutique.'}, + chartSet:{type:'boolean',doc:'The charter has been picked; false while the choice is still open.'}, + solWon:{type:'integer',doc:'The day the Speed of Light win landed (boutique charter), or 0.'}, + lvl:{type:'integer',doc:'Customer level (unlocks customer types).'}, + ltv:{type:'integer',doc:'Level at which Tier 1 vendors were visible (title-screen pick).'}, + t1v:{type:'integer',doc:'Level at which Tier 1 transit was offered.'}, + auV:{type:'integer',doc:'Australia content level gate.'}, + seen:{type:'array',doc:'Network ids the deals panel has already shown. Vestigial: written by newGame, read nowhere.'}, + pops:{type:'map',doc:'Your POPs by city id: day opened, broadband (bb), ad boost, downtime, routers, generator, second site.'}, + links:{type:'array',doc:'Your links: waves, dark fiber (df), own cables and fabric circuits (vxc), each with an entity id.'}, + transit:{type:'array',doc:'Transit ports: city, net, tier, LAG members, port history for 95th-percentile billing.'}, + ixp:{type:'map',doc:'IX ports by exchange city; tier per port (may exceed 1 with LAG members in ixn).'}, + rs:{type:'map',doc:'Route-server sessions by exchange city.'}, + ixn:{type:'map',doc:'LAG members on IX ports by exchange city.'}, + ixSite:{type:'map',doc:'Which building each IX port sits in (a, b or ab).'}, + ixPref:{type:'map',doc:'Egress preference per IX port.'}, + myIx:{type:'map',doc:'Exchanges you founded: name, members, join schedule, fabric step.'}, + peers:{type:'map',doc:'Peering sessions, keyed "net@ix".'}, + pairMet:{type:'map',doc:'Routing metric per city pair (prefer/avoid/backup/normal), keyed by pair.'}, + pni:{type:'array',doc:'Private interconnects: city, net, tier, ready day, augments (up), LAG, sacrificial flag.'}, + caches:{type:'array',doc:'CDN cache boxes: city, net, building.'}, + nni:{type:'array',doc:'Fabric ports: city, provider, tier.'}, + biz:{type:'array',doc:'Signed customers: type, cities, bandwidth, rate, mood, contract dates.'}, + offers:{type:'array',doc:'Pending customer offers, each expiring on a day.'}, + done:{type:'map',doc:'Goals landed, by goal id → day.'}, + ach:{type:'map',doc:'Badges earned this game, by badge id → day.'}, + inc:{type:'array',doc:'Open incidents: type, what they hit, until when, optional rush-repair price.'}, + ddosStarts:{type:'array',doc:'The days the attacks of the last week started; at most 14 a week.'}, + ev:{type:'map',doc:'Live world events: the running DDoS, route leaks, fabric failures, price shocks.'}, + stats:{type:'map',doc:'Counters: incidents survived, loans taken, sharks, conferences attended, peak traffic…'}, + log:{type:'array',doc:'The NOC notification feed, newest first, capped at 60; identical notices within a minute fold with a count.'}, + nextFail:{type:'integer',doc:'The day the next failure fires.'}, + nextEvent:{type:'integer',doc:'The day the next world event fires.'}, + rng:{type:'integer',doc:'The scenario seed; it predicts every future random draw.'}, + usedNames:{type:'array',doc:'Customer names already handed out.'}, + spares:{type:'map',doc:'Spare optics on the shelf, by optic id.'}, + scrubs:{type:'array',doc:'Scrubbing centres: city and tier.'}, + scrubMode:{type:'string',doc:'always | ondemand.'}, + cnLic:{type:'map',doc:'Mainland China licence: none | pending (with ready day) | ok.'}, + ppol:{type:'string',doc:'Your published peering policy: open | selective | closed.'}, + pdesk:{type:'map',doc:'This week\'s peering desk summary: sessions accepted and declined at which exchanges.'}, + pdeskRep:{type:'map',doc:'Last week\'s peering desk summary, as the NOC log reported it.'}, + ops:{type:'map',doc:'The NOC intern: who is hired, each standing order\'s on/off switch and settings, the monthly budget and what it spent, per-POP exceptions, the new-POP template and the weekly log.'}, + core:{type:'map',doc:'Your backbone technology: lv bought, the level it runs at, the interop lab.'}, + ddosAuto:{type:'map',doc:'The NOC\'s auto-mitigation switches: rtbh and scrub.'}, + popStd:{type:'map',doc:'The standard POP: router model and count new POPs start with, or null for none.'}, + demo:{type:'map',doc:'Vendor demo units on order, by "kind:id" → ready day.'}, + seatOff:{type:'map',doc:'The pending consortium-cable seat offer: landings, km, name, expiry day.'}, + monkey:{type:'map',doc:'The chaos monkey: next visit day, whether it is in your network now, days left, whether anyone noticed.'}, + fleet:{type:'map',doc:'Cable-ship voyages by ship id: the cut it sails to, when it arrives, splices and comes home.'}, + achP:{type:'map',doc:'Which rule set each badge was earned under (oncall, freeze, bgp), by badge id.'}, + calV:{type:'integer',doc:'Calendar save-format marker: 1 once the real calendar (28-31-day months) applies.'}, + pz:{type:'map',doc:'The running puzzle: its id, cities, flows to deliver, budget and stars.'}, + ar:{type:'map',doc:'The running architect run: its HQ, brief index, gold sites, spend and the build it started from.'}, + loans:{type:'array',doc:'Active loans: bank, balance, APR, term, share (equity banks).'}, + loanOffers:{type:'array',doc:'Pending loan offers.'}, + loanStrikes:{type:'integer',doc:'How many loan offers you have let lapse.'}, + confReg:{type:'map',doc:'Conferences registered for, by key; "sp" when sponsoring.'}, + hw:{type:'map',doc:'Hardware market: price shocks and any price lock.'}, + capDeal:{type:'map',doc:'The pending capacity deal from a capacity conference.'}, + cam:{type:'map',doc:'Map camera position. View state that save() happens to store inside S.'}, + uiSpeed:{type:'number',doc:'The speed you left the game at. View state that save() stores inside S.'}, + won:{type:'boolean',doc:'You reached Tier 1.'}, + t1Now:{type:'boolean',doc:'Tier 1 right now, as of the last day; falling out of it is announced.'}, + lost:{type:'boolean',doc:'The bank repossessed the routers.'}, + neg:{type:'integer',doc:'Days in the red in a row.'}, + hist:{type:'array',doc:'Daily history for the graphs: demand, served, exit split, revenue, cost, cash.'}, + scn:{type:'map',doc:'The running scenario: id, rules, day limit, done/failed, and the day of the next scripted attack (nextDdos).'}, + dk:{type:'map',doc:'De-Kicks state: per-exchange multipliers, add-ons, retention, the live quote (q) and the remembered one (lastQ).'}, + grace:{type:'map',doc:'Courtesy transit after a merger wave, until a day.'}, + merged:{type:'map',doc:'Networks merged into others this game.'}, + tut:{type:'map',doc:'Tutorial progress.'}, + conf:{type:'map',doc:'The conference glow: region and until when; sp when you sponsored.'}, + phpDone:{type:'boolean',doc:'One-shot flag.'}, + krExit:{type:'map',doc:'Korea exit state.'}, + auNews:{type:'boolean',doc:'One-shot flag: the Australia news toast.'}, + richTold:{type:'boolean',doc:'One-shot flag: the cash milestone toast.'}, +}; + +const API_RESULTS_DOC={ + nt:{type:'map',doc:'Traffic per network through transit, by net id.'}, + tNet:{type:'map',doc:'Traffic per network you hand to each upstream, by "net@upstream".'}, + reachNT:{type:'number',doc:'Networks reachable without transit.'}, + teBlack:{type:'number',doc:'Traffic blackholed by RouteScript rules.'}, + teMoved:{type:'number',doc:'Traffic Auto-TE spilled onto alternate paths.'}, + egT:{type:'map',doc:'Egress split by exit kind (c/p/ix/t/l2) in Gbps.'}, + egDesc:{type:'map',doc:'RouteScript drains per exit.'}, + netEg:{type:'map',doc:'Per-network egress split: which exit carries which network.'}, + ef:{type:'map',doc:'LAZY per-link exit breakdown: what crosses each link, per network, built only when a panel asks. What is in here depends on which panels have rendered.'}, + l2:{type:'map',doc:'Layer-2 traffic per customer (L2VPN, SD-WAN, waves).'}, + l2lat:{type:'map',doc:'Latency per L2 customer.'}, + l2route:{type:'map',doc:'Which path an L2 customer\'s traffic takes.'}, + l2split:{type:'map',doc:'L2 traffic split per path.'}, + nodeLoad:{type:'map',doc:'Router forwarding load per city.'}, + nodeCap:{type:'map',doc:'Router forwarding capacity per city.'}, + div:{type:'map',doc:'Traffic diversity per customer (how split their paths are).'}, + gfwLost:{type:'number',doc:'Traffic lost to the Great Firewall.'}, + gfwCross:{type:'number',doc:'Traffic crossing into mainland China.'}, + p95:{type:'map',doc:'95th-percentile transit readings per port.'}, + peered:{type:'number',doc:'Share of traffic that stays on peering.'}, + peerShare:{type:'number',doc:'Fraction of traffic served by peers (mood driver).'}, + load:{type:'map',doc:'Load per link in Gbps.'}, + useT:{type:'map',doc:'Transit use per port id.'}, + useIx:{type:'map',doc:'IX use per exchange city.'}, + usePni:{type:'map',doc:'PNI use per port id.'}, + useCache:{type:'map',doc:'Cache use per box id.'}, + cityDem:{type:'map',doc:'Eyeball + customer demand per city.'}, + citySrv:{type:'map',doc:'Traffic served per city.'}, + cityEye:{type:'map',doc:'Eyeballs online per city.'}, + latF:{type:'map',doc:'Fraction of each city\'s traffic that goes far (over a threshold latency).'}, + latFar:{type:'map',doc:'The far exit each slow city sends traffic through.'}, + demTo:{type:'map',doc:'Your traffic destined to each network, in Gbps. The number CDN caches ask about.'}, + served:{type:'number',doc:'Total traffic served, in Gbps.'}, + demand:{type:'number',doc:'Total traffic demanded, in Gbps.'}, + reach:{type:'number',doc:'Fraction of the internet you can reach (0..1).'}, + sessions:{type:'number',doc:'Peering sessions up.'}, + revMo:{type:'number',doc:'Revenue per month.'}, + costMo:{type:'number',doc:'Cost per month.'}, + cost:{type:'map',doc:'Monthly cost by category (transit, pni, ix, links…).'}, + rev:{type:'map',doc:'Monthly revenue by source.'}, + reachable:{type:'map',doc:'Networks reachable per net id.'}, + cone:{type:'map',doc:'Which peer\'s customer cone carries each network you reach without transit of your own, by net id.'}, + ddos:{type:'array',doc:'Per live attack: the target, its size, which ports it fills, what Flowspec and each scrubbing centre cleaned, and what reaches the target.'}, + haul:{type:'array',doc:'Scrubbing detours: from the attacked city to each centre, one-way latency and how much they carry.'}, + tgtF:{type:'map',doc:'The share of a targeted customer\'s traffic that survives the attack, by customer id.'}, + bbF:{type:'map',doc:'The share of a city\'s broadband subscribers that survive an attack on them, by city id.'}, + fsUse:{type:'map',doc:'Flowspec rules in use per city: used of the routers\' rule capacity.'}, + bizDem:{type:'map',doc:'Business customers\' share of each city\'s demand, in Gbps (what RouteScript\'s protect customers serves first).'}, + bizSrv:{type:'map',doc:'Of that business demand, what was served, per city.'}, + graceNets:{type:'number',doc:'Networks reached over the courtesy route after a merger wave.'}, + cityBlocked:{type:'map',doc:'Set up per city by the traffic computation; nothing fills it at present.'}, + ddosHot:{type:'map',doc:'Cities whose ports a flood is filling, for the map\'s pulse. Keyed by city id.'}, +}; diff --git a/src/agent/40-read.js b/src/agent/40-read.js new file mode 100644 index 0000000..9a5a123 --- /dev/null +++ b/src/agent/40-read.js @@ -0,0 +1,217 @@ +/* ================= AGENT API: reading the game ================= + Every function takes and returns plain JSON and only reads the game. */ +/* Dotted subtrees, no wildcards. An array walks by index (`biz.3`) or by entity id (`links[#id]`). */ +function apiPath(o,p){ + if(p===undefined||p===null||p==='')return o; + let v=o; + for(const k of String(p).split('.')){ + if(v==null)return undefined; + if(Array.isArray(v)){const i=Number(k); + v=(Number.isInteger(i)&&String(i)===k&&i>=0&&ix&&typeof x==='object'&&x.id===k);} + else if(v instanceof Set)v=[...v]; + else if(v instanceof Map)v=Object.fromEntries(v); + else if(typeof v==='object')v=v[k]; + else return undefined;} + return v;} + +function apiJson(v){ + if(v instanceof Set)return [...v].map(apiJson); + if(v instanceof Map)return apiJson(Object.fromEntries(v)); + if(v&&typeof v==='object')return Array.isArray(v)?v.map(apiJson):Object.fromEntries(Object.entries(v).map(([k,x])=>[k,apiJson(x)])); + if(typeof v==='function')return undefined; + return v;} + +/* The tables the argument domains point at. Everything is a static reference except three, + each computed for a reason: BADGES hides unearned secrets like the badge wall; conferences + carries the keys confGo/confSponsor need, which exist in no field of S; TE_RECIPES renders + each recipe's script, because the source is a function and some read the live network. The + recipes' relevance score is not exposed: judging which one fits is the agent's job. */ +const API_TABLES={CITIES,NETS,CABLES,XIX,PORT,LT,NNI,VXC,RG,OPT,DF_SYS,FAB,SCRUB_TIERS,BIZ_T,LEVELS,GOALS,SCN,BANKS,REQS,NSH,MET,PREF,RT,PPOL,CONFS,LAG_MAX,RMAX,REGEN_MAX,START_CASH,CONF_COST,CONF_SP,CAP_COST,CAP_LV,CONF_DAYS,SUB_UPGRADES,SEA_DESIGNS,TE_COST,TE_MO,MYIX_COST,CN_LIC,SITE2_COST,MYIX_FAB,INTERNS,OPSK,CHARTERS,SEAT_N,CORE_LV,CORE_COST,CORE_REQ,CORE_LAB,INTERN_MO,PZ_TIERS,AR_TIERS,PZ_RG}; +const API_MADE={ + BADGES:()=>!S?[]:BADGES.map(b=>{const on=S.ach&&S.ach[b.id]!==undefined,ever=!!hof()[b.id]; + return b.secret&&!on&&!ever?{id:b.id,i:'❔',t:'???',d:tr('badges.a_secret_badge'),r:b.r,secret:true}:{...b,ever};}), + conferences:()=>!S?[]:upcomingConfs(75).map(cf=>({key:cf.key,name:cf.n,city:cf.c,day:cf.day,capacity:!!cf.cap,cost:confCost(cf),sponsorCost:confSp(cf)?CONF_SP:null})), + TE_RECIPES:()=>!S?[]:TE_RECIPES.map(r=>({id:r.id,name:tr(r.n),description:tr(r.d),script:r.src().join('\n')})), +}; +function API_CATALOG_TABLE(name){return name in API_MADE?API_MADE[name]():API_TABLES[name];} + +/* UI minus the render caches and pointer scratch, which are inputs to nothing. + Everything a command binds (pending, route, via, dfSrc, dfSys, seaDesign, cnPrem, decom, + teDraft, confirm) stays, so an agent can see what it was given. */ +const API_UI_HIDDEN={_lh:1,_ph:1,_tb:1,_layer:1,layerAt:1,hover:1,drag:1,snap:1}; + +/* ---------- text as a player reads it ---------- */ +const API_BLOCK=/^(DIV|P|H1|H2|H3|H4|SECTION|LI|UL|OL|TR|TABLE|NAV|HEADER|FOOTER|BUTTON|LABEL|DETAILS|SUMMARY)$/,API_MAX_TEXT=8000; +// One line per block, no runs of spaces. jsdom has no innerText, so this walks the nodes itself. +function apiFullText(x){ + let el=x; + if(typeof x==='string'){el=document.createElement('div');el.innerHTML=x;} + if(!el)return ''; + const out=[]; + const walk=n=>{ + if(n.nodeType===3){out.push(n.nodeValue);return;} + if(n.nodeType!==1||n.hidden||/^(SCRIPT|STYLE|SVG|CANVAS)$/i.test(n.tagName))return; + if(n.tagName==='BR'){out.push('\n');return;} + // A dropdown reads as its choice: hundreds of options would crowd out the rest (the catalog lists them). + if(n.tagName==='SELECT'){const o=n.options[n.selectedIndex];out.push(' ',o?o.text:'',' ');return;} + // Blocks get their own line; inline tags a space, so "Revenue$2k" does not read as one word. + const sep=API_BLOCK.test(n.tagName)?'\n':' '; + out.push(sep);for(const c of n.childNodes)walk(c);out.push(sep);}; + walk(el); + return out.join('').split('\n').map(l=>l.replace(/\s+/g,' ').replace(/ ([.,;:!?)])/g,'$1').replace(/\( /g,'(').trim()).filter(Boolean).join('\n');} +const apiText=(x,max=API_MAX_TEXT)=>{const s=apiFullText(x);return s.length>max?s.slice(0,max)+'\n…':s;}; +const apiR1=v=>typeof v==='number'&&isFinite(v)?Math.round(v*10)/10:v; +const apiFail=msg=>{throw new Error(msg);}; +const apiNorm=s=>String(s||'').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g,'').trim(); +const apiParse=s=>{try{return JSON.parse(s||'{}');}catch(e){return {};}}; + +/* ---------- finding things by id or by name ---------- */ +function apiBest(list,q,keys){const n=apiNorm(q);if(!n)return null; + for(const test of [v=>v===n,v=>v.startsWith(n),v=>v.includes(n)]){const hit=list.find(x=>keys(x).some(k=>test(apiNorm(k))));if(hit)return hit;} + return null;} +const apiNetOf=q=>NET[q]||apiBest(NETS,q,n=>[n.id,n.name,'as'+n.asn,String(n.asn)])||apiFail(`No network matches "${q}". Try find.`); +const apiCityOf=q=>CITY[q]||apiBest(CITIES,q,c=>[c.id,c.name])||apiFail(`No city matches "${q}". Try find.`); +function apiAllIx(){const o=[];for(const c of CITIES)for(const x of ixStatic(c.id))o.push(x);for(const c of Object.keys(S.myIx||{}))if(!o.includes(c))o.push(c);return o;} +const apiCityName=c=>CITY[c]?CITY[c].name:c; +const apiIncText=i=>apiText(i.msg||incTitle(i),400); +const apiMyPops=()=>Object.keys(S.pops).map(apiCityName).join(', '); + +/* ---------- the network at a glance, and the world ---------- */ +function apiStatus(){ + const goal=GOALS.find(g=>S.done[g.id]===undefined),t1=isTier1(),k=o=>Object.fromEntries(Object.entries(o||{}).map(([a,v])=>[a,Math.round(v)]).filter(([,v])=>v)); + return { + name:S.name,asn:S.asn,home:apiCityName(S.home),mode:S.mode,rules:S.rules&&S.rules.preset, + day:S.day,date:dateStr(S.day),cash:Math.round(S.cash),level:S.lvl||0, + tier:tierLabel(),whyNotTier1:t1?null:apiText(t1Why()), + goal:goal?{title:apiText(goal.t),what:apiText(goal.d)}:null, + monthly:{revenue:Math.round(R.revMo),cost:Math.round(R.costMo),profit:Math.round(R.revMo-R.costMo),revenueBy:k(R.rev),costBy:k(R.cost)}, + traffic:{demandGbps:apiR1(R.demand),servedGbps:apiR1(R.served),reach:apiR1((R.reach||0)*100)+'%',peeringSessions:R.sessions}, + counts:{pops:Object.keys(S.pops).length,links:S.links.length,transitPorts:S.transit.length,exchangePorts:Object.keys(S.ixp).length, + pnis:S.pni.length,cacheBoxes:S.caches.length,customers:S.biz.length,offers:S.offers.length}, + pops:Object.keys(S.pops).map(apiCityName), + incidents:S.inc.map(i=>({id:i.id,type:i.type,what:apiIncText(i),until:i.until!==undefined?dateStr(i.until):undefined,rushRepairCost:i.cost||undefined})), + lost:!!S.lost,won:!!S.won, + };} + +function apiNetwork(q){ + const n=apiNetOf(q),id=n.id,eg=R.netEg&&R.netEg[id]; + return { + id,name:n.name,asn:n.asn,type:TYPE_L[n.type],policy:n.pol, + requirements:{minIxGbps:n.minIx,minPniGbps:n.minPni,paidFeePerMonth:n.paidFee,freeFromLevel:n.freeLv}, + trafficShare:apiR1(NSH[id]*100)+'%',transitPerGbps:n.price?apiR1(n.price*S.priceMul):null, + homeMarkets:n.cc?[].concat(n.cc):[],pops:n.pops.map(apiCityName), + exchanges:n.ix==='ALL'?'most exchanges where it has a PoP':(n.ix||[]).map(x=>ixName(x)), + upstreams:(n.up||[]).map(u=>NET[u]?NET[u].name:u),customerCone:(DOWN[id]||[]).length, + neededForTier1:t1Need().some(x=>x.id===id),mergedInto:merged(id)?(MERGERS.find(m=>m.id===id)||{}).into:undefined, + about:apiText(n.blurb), + you:{ + reachable:!!(R.reachable&&R.reachable[id]),demandGbps:apiR1((R.demTo&&R.demTo[id])||0), + egressGbps:eg?Object.fromEntries(Object.entries(eg).map(([k,v])=>[k,apiR1(v)])):null, + pnis:S.pni.filter(p=>p.net===id).map(p=>({id:p.id,city:apiCityName(p.city),port:pniPN(p),count:p.n||1,ready:pniOn(p)})), + exchangeSessions:Object.keys(S.ixp).filter(x=>ixSessions(x).has(id)).map(ixName), + howToPeer:apiText(offTransitHint(id,S.home)), + }, + };} + +function apiCity(q){ + const C=apiCityOf(q),c=C.id,P=S.pops[c]; + const cab=CABLE_PAIRS.filter(p=>p.a===c||p.b===c).map(p=>({cable:CAB[p.cid]?CAB[p.cid].name:p.cid,to:apiCityName(p.a===c?p.b:p.a),km:p.km})); + const here=NETS.filter(n=>n.pops.includes(c)&&!n.tail).sort((a,b)=>b.share-a.share); + return { + id:c,name:C.name,country:C.cc,region:C.reg,about:C.note?apiText(C.note):undefined,dataCenter:C.dc, + canBeHome:homeOk(c), + exchanges:ixIdsIn(c).map(x=>({id:x,name:ixName(x),members:ixMembers(x).length,yourPort:S.ixp[x]!==undefined})), + transit:NETS.filter(n=>sellsAt(n,c)).map(n=>({id:n.id,name:n.name,type:TYPE_L[n.type],perGbps:apiR1(transitPerG(n,c,false)*S.priceMul)})).sort((a,b)=>a.perGbps-b.perGbps), + networksHere:here.length,biggestNetworksHere:here.slice(0,15).map(n=>n.name),cables:cab, + you:P?{demandGbps:apiR1((R.cityDem||{})[c]||0),servedGbps:apiR1((R.citySrv||{})[c]||0),routers:P.routers,down:P.down>S.day?dateStr(P.down):false, + broadband:!!P.bb,links:S.links.filter(l=>l.a===c||l.b===c).length}:null, + };} + +function apiFind(q,kind){ + const n=apiNorm(q),hit=(...k)=>k.some(v=>apiNorm(v).includes(n)),out={}; + if(!n)apiFail('Give a word to search for.'); + if(!kind||kind==='city')out.cities=CITIES.filter(c=>hit(c.id,c.name)).slice(0,20).map(c=>({id:c.id,name:c.name,country:c.cc})); + if(!kind||kind==='network')out.networks=NETS.filter(x=>hit(x.id,x.name,String(x.asn))).slice(0,20).map(x=>({id:x.id,name:x.name,asn:x.asn,type:TYPE_L[x.type]})); + if(!kind||kind==='cable')out.cables=Object.values(CAB).filter(x=>hit(x.id,x.name)).slice(0,20).map(x=>({id:x.id,name:x.name,lands:[...new Set(x.pairs.flatMap(p=>[p[0],p[1]]))].map(apiCityName)})); + if(!kind||kind==='exchange')out.exchanges=apiAllIx().filter(x=>hit(x,ixName(x))).slice(0,20).map(x=>({id:x,name:ixName(x),city:apiCityName(ixCity(x))})); + return out;} + +function apiTrace(from,to){ + const src=apiCityOf(from).id; + if(!S.pops[src])apiFail(`You have no POP in ${apiCityName(src)}. Yours: ${apiMyPops()}.`); + let target=null; + if(typeof to==='string'&&/^city:/i.test(to))target={city:apiCityOf(to.slice(5)).id}; + else{try{target={net:apiNetOf(to).id};}catch(e){target={city:apiCityOf(to).id};}} + if(target.city&&!S.pops[target.city])apiFail(`A traceroute to a city goes to one of your POPs: ${apiMyPops()}.`); + const r=traceroute(src,target); + return {text:r.text,why:apiText(r.why||''),asPath:r.asPath||null};} + +function apiPeering(q,where,via){ + const n=apiNetOf(q),id=n.id,out=[]; + if(!via||via==='pni')for(const c of (where?[apiCityOf(where).id]:Object.keys(S.pops).filter(c=>n.pops.includes(c)))){ + const r=peerOk(id,'pni',c); + out.push({via:'pni',city:apiCityName(c),ok:!!r.ok,why:r.why?apiText(r.why):undefined,feePerMonth:r.fee,free:r.free,minimumPort:PORT[pniMin(id)].n});} + if(!via||via==='ix')for(const x of Object.keys(S.ixp).filter(x=>ixMembers(x).includes(id)&&(!where||ixCity(x)===apiCityOf(where).id))){ + const r=peerOk(id,'ix',x); + out.push({via:'ix',exchange:ixName(x),ok:!!r.ok,why:r.why?apiText(r.why):undefined,session:ixSessions(x).has(id)});} + return {network:n.name,policy:n.pol,hint:apiText(offTransitHint(id,where?apiCityOf(where).id:S.home)), + checks:out,note:out.length?undefined:'No POP or exchange port of yours is where this network is. Build one first: see network.'};} + +function apiHotSpots(limit=10){ + const top=a=>a.sort((x,y)=>y.util-x.util).slice(0,limit),pct=(u,c)=>c>0?apiR1((u/c)*100):null; + const links=S.links.map(l=>{const cap=capOf(l),u=(R.load||{})[l.id]||0;return {id:l.id,between:apiCityName(l.a)+' – '+apiCityName(l.b),kind:l.kind,capacity:capName(l),usedGbps:apiR1(u),util:pct(u,cap),down:linkDown(l)};}); + const transit=S.transit.map(t=>{const cap=lagCap(PORT[t.tier].g,t.n),u=(R.useT||{})[t.id]||0,q=(R.p95&&R.p95[t.id])||u; + return {id:t.id,city:apiCityName(t.city),carrier:NET[t.net].name,port:lagName(t.tier,t.n),usedGbps:apiR1(u),util:pct(u,cap),billPerMonth:Math.round(transitMo(t,q))};}); + const pnis=S.pni.filter(pniOn).map(p=>{const cap=pniG(p)*(p.n||1),u=(R.usePni||{})[p.id]||0;return {id:p.id,network:NET[p.net].name,city:apiCityName(p.city),port:pniPN(p),usedGbps:apiR1(u),util:pct(u,cap)};}); + const viaTransit=NETS.filter(n=>R.netEg&&R.netEg[n.id]&&R.netEg[n.id].t>0.05).sort((a,b)=>R.netEg[b.id].t-R.netEg[a.id].t).slice(0,limit) + .map(n=>({id:n.id,network:n.name,overTransitGbps:apiR1(R.netEg[n.id].t),howToPeer:apiText(offTransitHint(n.id,S.home))})); + const bill={};for(const t of transit)bill[t.carrier]=(bill[t.carrier]||0)+t.billPerMonth; + return {links:top(links),transitPorts:top(transit),pnis:top(pnis),transitBillByCarrier:bill,biggestTrafficStillOnTransit:viaTransit};} + +/* ---------- the contract: commands, arguments, reference tables, raw state ---------- */ +const apiDenied=name=>own(API_DENY,name)?API_WHY[API_DENY[name]]:null; +const apiKind=name=>API_CMD[name]?'game':API_VIEW[name]?'view':API_BOUND[name]?'draft':API_SESSION[name]?'session':null; +const apiSpec=name=>API_CMD[name]||API_VIEW[name]||API_SESSION[name]||null; +const apiClasses=()=>({game:Object.keys(API_CMD),view:Object.keys(API_VIEW),draft:Object.keys(API_BOUND),session:Object.keys(API_SESSION),denied:Object.keys(API_DENY)}); + +// One argument as the schema states it. Table domains name their catalog table rather than list every id. +function apiArgDoc([name,dom,req]){ + const a={name,required:req!==false},d=API_DOMAINS[dom]; + if(!d){a.type=dom;return a;} + a.domain=dom; + if(d.table)a.from=d.table; + else{const v=apiDomValues(dom);if(Array.isArray(v))a.values=v;else if(v&&v.from!==undefined)a.range=v;} + return a;} +function apiSchema(section){ + const cmd=s=>({args:(s.args||[]).map(apiArgDoc),doc:s.doc}); + const doc={ + clock:apiClockDoc(), + commands:Object.fromEntries(Object.entries(API_CMD).map(([n,s])=>[n,{...cmd(s),dryRun:!!s.quote, + ...(s.decides?{decides:true}:{}),...(s.confirm?{confirm:s.confirm}:{}),...(s.open?{opens:s.open}:{}),...(s.reads?{report:true}:{})}])), + view:Object.fromEntries(Object.entries(API_VIEW).map(([n,s])=>[n,cmd(s)])), + session:Object.fromEntries(Object.entries(API_SESSION).map(([n,s])=>[n,cmd(s)])), + drafts:API_BOUND, + denied:Object.fromEntries(Object.keys(API_DENY).sort().map(n=>[n,apiDenied(n)])), + domains:Object.fromEntries(Object.entries(API_DOMAINS).map(([n,d])=>{const v=apiDomValues(n); + return [n,{kind:d.kind==='fn'?'custom':d.kind,...(d.table?{from:d.table}:{}), + ...(!d.table&&Array.isArray(v)?{values:v}:v&&v.from!==undefined?{range:v}:v&&v.of?{of:v.of}:{})}];})), + state:API_STATE_DOC, + results:API_RESULTS_DOC, + }; + if(section===undefined||section===null||section==='')return doc; + if(!(section in doc))apiFail(`No section "${section}". Sections: ${Object.keys(doc).join(', ')}.`); + return doc[section];} +function apiCatalog(name){ + if(name===undefined||name===null||name===''){ + return {tables:[...Object.keys(API_TABLES),...Object.keys(API_MADE)].sort().map(k=>{const t=k in API_MADE?API_MADE[k]():API_TABLES[k]; + return {name:k,n:Array.isArray(t)?t.length:t&&typeof t==='object'?Object.keys(t).length:1};})};} + if(name in API_MADE)return apiJson(API_MADE[name]()); + if(name in API_TABLES)return apiJson(API_TABLES[name]); + apiFail(`No table "${name}". Call catalog without a name for the list.`);} +function apiState(path){if(!S)return null;const v=apiJson(apiPath(S,path));return v===undefined?null:v;} +function apiResults(path){const v=apiJson(apiPath(R,path));return v===undefined?null:v;} +function apiUi(){const o={};for(const k of Object.keys(UI))if(!API_UI_HIDDEN[k])o[k]=apiJson(UI[k]);return o;} +function apiActions(){ + const sig=s=>(s.args||[]).map(a=>a[0]+(a[2]===false?'?':'')).join(','),typed={}; + for(const t of [API_CMD,API_VIEW,API_SESSION])for(const [n,s] of Object.entries(t))typed[n]=sig(s); + return {typed,drafts:Object.keys(API_BOUND)};} diff --git a/src/agent/50-screen.js b/src/agent/50-screen.js new file mode 100644 index 0000000..58a2c8d --- /dev/null +++ b/src/agent/50-screen.js @@ -0,0 +1,64 @@ +/* ================= AGENT API: what is on screen ================= + The surfaces a player can read, as text with numbered buttons, by the name screen takes. The left drawer has tabs + (goals, deals, noc, nets). */ +const API_ROOT={modal:'modal',bank:'bankBox',dash:'dash',panel:'panel',left:'leftBody',puzzle:'pzBox'}; +const apiShown=w=>{const el=$(API_ROOT[w]);return !!el&&!el.hidden;}; +const apiModalOpen=()=>apiShown('modal'); +// The buttons of the last screen a tool read, for click. Set by apiScreen. +let API_LAST=[]; +function apiControls(root){ + const out=[]; + for(const b of root.querySelectorAll('[data-act],select[data-chg]')){ + const o=b.dataset.act?{label:apiText(b,200).replace(/\n/g,' ')||b.getAttribute('aria-label')||b.dataset.act,act:b.dataset.act,args:apiParse(b.dataset.args),disabled:!!b.disabled} + // A list the game acts on when its value changes (the change handler in 96-map/95-clicks.js): click it with a value. + :{label:b.getAttribute('aria-label')||(b.closest('label')&&apiText(b.closest('label'),120).split('\n')[0])||b.dataset.chg, + select:b.dataset.chg,value:b.value,options:[...b.options].map(o=>({value:o.value,label:o.textContent.trim()})),disabled:!!b.disabled}; + out.push(o);} + return out;} +function apiScreen(where,offset=0){ + if(where===null)where=undefined; + if(where!==undefined&&!API_ROOT[where])apiFail(`where is one of ${Object.keys(API_ROOT).join(', ')}.`); + const open=Object.keys(API_ROOT).filter(w=>w!=='left'&&apiShown(w)); + const w=where||['modal','bank','dash','panel','puzzle'].find(apiShown)||'panel'; + const root=$(API_ROOT[w]); + API_LAST=root?apiControls(root):[]; + const all=root?apiFullText(root):'',from=Math.max(0,Math.floor(+offset)||0),more=all.length-from-API_MAX_TEXT; + const out={where:w,open,selected:UI.sel,tab:UI.tab}; + if(w==='left')out.leftTab=UI.left||'goals'; + if(w==='modal')out.question=!!apiDecision(); + out.text=all.slice(from,from+API_MAX_TEXT); + if(from)out.textFrom=from; + if(more>0)out.textMore=`${more} more characters: call screen with where "${w}" and offset ${from+API_MAX_TEXT}`; + out.buttons=API_LAST.map((b,i)=>({n:i,...b})); + return out;} + +/* ---------- windows: the tool's own sheets, and the game's questions ---------- + A window the tool opened itself (a view, a draft, the link window, a sheet it clicked inside) is something to read + and click through. A window the game opened in answer to a game command, or during a day, is a question when one + of its buttons runs a game command other than closeModal (a De-Kicks quote, a retention offer); then other game + commands wait until it is answered or closed, as clicks outside an open window do in the game. */ +let API_SHEET=null; +const apiCard=()=>$('modalCard').firstChild; +const apiMarkSheet=()=>{API_SHEET=apiModalOpen()?apiCard():null;}; +const apiIsSheet=()=>apiModalOpen()&&!!API_SHEET&&apiCard()===API_SHEET; +function apiDecision(){ + if(!apiModalOpen()||apiIsSheet())return null; + const b=[...$('modal').querySelectorAll('[data-act]')].filter(x=>x.dataset.act!=='closeModal'&&API_CMD[x.dataset.act]); + if(!b.length)return null; + return {text:apiText($('modal'),1500),options:b.map(x=>({command:x.dataset.act,args:apiParse(x.dataset.args),label:apiText(x,120).replace(/\n/g,' ')}))};} + +function apiPanel({city:c,link,network:q,tab,left}={}){ + if(left!==undefined){if(!['goals','deals','noc','nets'].includes(left))apiFail('left is one of goals, deals, noc, nets.');ACT.leftTab({t:left});return apiScreen('left');} + if(c)UI.sel={type:'city',id:apiCityOf(c).id}; + else if(link){if(!S.links.some(l=>l.id===link))apiFail(`No link ${link}. See status or hot_spots for link ids.`);UI.sel={type:'link',id:link};} + else if(q)ACT.netFocus({id:apiNetOf(q).id}); + if(tab)UI.tab=tab; + renderAll(); + return apiScreen(q?'left':'panel');} +function apiOpenLink(a,b){ + const x=apiCityOf(a).id,y=apiCityOf(b).id; + if(!S.pops[x])apiFail(`A link starts at one of your POPs: ${apiMyPops()}.`); + apiTake(); + openLinkModal(x,y); + apiMarkSheet(); + return {toasts:apiToastLines(apiTake()),screen:apiScreen()};} diff --git a/src/agent/60-dispatch.js b/src/agent/60-dispatch.js new file mode 100644 index 0000000..c3f2cd7 --- /dev/null +++ b/src/agent/60-dispatch.js @@ -0,0 +1,114 @@ +/* ================= AGENT API: doing things ================= + One action, run as the game runs it, and reported through the game's own channels: what it said (toast), what it + charged at the money gate (spend) and whether anything changed (a fingerprint of S). The API checks shape and domain + only; whether a move is allowed is the game's to answer. */ + +// Arguments: shape and domain only. Anything beyond that is the game's to answer. +function apiValidate(spec,args){ + const problems=[],out={}; + for(const [name,dom,req] of spec.args||[]){ + const v=args[name]; + if(v===undefined){if(req!==false)problems.push(`${name} is required`);continue;} + if(apiDomCheck(dom,v).ok){out[name]=v;continue;} + const vs=apiDomValues(dom),d=API_DOMAINS[dom]; + problems.push(`${name}: ${JSON.stringify(v)} is not a ${dom}${d&&d.table&&d.kind==='id'?` (see catalog ${d.table} or find)`:Array.isArray(vs)?` (one of ${vs.slice(0,12).join(', ')}${vs.length>12?'…':''})`:vs&&typeof vs==='object'&&vs.from!==undefined?` (${vs.from}..${vs.to})`:''}`);} + for(const k of Object.keys(args))if(!(spec.args||[]).some(a=>a[0]===k))problems.push(`${k} is not an argument of this action`); + return {ok:!problems.length,problems,args:out};} + +// The fingerprint tells "did nothing" from "did something quietly": cash, day, the entity counts, the small settings +// maps, and the paths a command declares in watch. R is left out: it is rebuilt after every action. +const API_FP_LEN=['links','transit','pni','caches','biz','offers','nni','loans','loanOffers','inc','scrubs']; +const API_FP_KEYS=['pops','ixp','peers','myIx','done','ach','merged','confReg']; +const API_FP_JSON=['name','pairMet','rs','ixn','ixSite','ixPref','spares','te','cnLic','hw','scrubMode','ppol','ops','core','ddosAuto','popStd','demo','charter','monkey','seatOff','pz','ar','dk','ev']; +function apiFp(watch,args){ + if(!S)return null; + const f={cash:S.cash,day:S.day,lvl:S.lvl||1,won:!!S.won,lost:!!S.lost}; + for(const k of API_FP_LEN)f[k]=(S[k]||[]).length; + for(const k of API_FP_KEYS)f[k]=Object.keys(S[k]||{}).length; + for(const k of API_FP_JSON)f[k]=JSON.stringify(apiJson(S[k])??null); + for(const p of watch||[])f['@'+p]=JSON.stringify(apiJson(apiPath(S,String(p).replace(/#(\w+)/g,(m,k)=>args&&args[k]!==undefined?args[k]:m)))??null); + return JSON.stringify(f);} +// spend() is the game's money gate and a top-level function, so every action reaches it by its global name. +function apiMeter(){const real=window.spend;let paid=0;window.spend=c=>{const ok=real(c);if(ok)paid+=c;return ok;};return ()=>{window.spend=real;return paid;};} + +/* typed: through the command table (bind the UI, type into fields, pass the confirmation); otherwise as a button click + does it, with the button's own arguments. */ +function apiDispatch(name,kind,spec,args,typed){ + const mine=apiIsSheet()||(typed&&kind==='game'&&!!spec.open); + apiTake(); + const ref=S,cash=S?S.cash:0,f0=apiFp(spec&&spec.watch,args),paid=apiMeter(); + let threw=null,report; + try{ + if(typed&&kind==='game'){ + if(spec.open){ACT[spec.open]({});apiMarkSheet();} + // The custom metric's field lives in the link's panel. + if(name==='metricSet'&&!$('metIn')){UI.sel={type:'link',id:args.id};renderAll();} + const gone=(spec.dom||[]).filter(f=>!$(f)); + if(gone.length)throw new Error(`the field it types into (${gone.join(', ')}) is not on screen${name==='metricSet'?': set the link\'s metric to custom first (setMetric v "custom")':''}`); + if(spec.bind)spec.bind(args); + const a=spec.pass?spec.pass(args):args; + ACT[name](a); + if(spec.confirm==='double')ACT[name](a); + if(spec.reads==='modal'&&apiModalOpen()){report=apiText($('modal'));closeModal();} + }else ACT[name](args); + }catch(e){threw=e;} + const charged=paid(); + if(threw){apiTake();apiFail(`${name} failed: ${threw&&threw.message||threw}`);} + if(!apiModalOpen())API_SHEET=null; + else if(mine||kind!=='game')apiMarkSheet(); + else API_SHEET=null; + const said=apiTake(),d=apiDecision(); + const outcome=d?'decision':S!==ref||apiFp(spec&&spec.watch,args)!==f0||report!==undefined?'applied' + :said.some(t=>t.kind==='bad')?'rejected':kind==='view'||kind==='draft'?'shown':'no_effect'; + return {action:name,outcome,toasts:apiToastLines(said),charged,cashChange:Math.round((S?S.cash:0)-cash), + ...(report!==undefined?{report}:{}),...(d?{decision:d}:{}),screen:apiScreen()};} +// While the game waits for an answer, game commands other than its options report the question instead. +function apiWaiting(name){ + const d=apiDecision(); + return d&&name!=='closeModal'&&!d.options.some(o=>o.command===name) + ?{action:name,outcome:'decision',reason:'A window is waiting for an answer: run one of its options, or closeModal.',decision:d,screen:apiScreen()}:null;} +function apiQuote(name,spec,args){ + const ui0={}; + for(const k of spec.bindsUI||[])ui0[k]=UI[k]; + const f0=apiFp(spec.watch,args); + // A dry run must not use up the dice: some helpers draw (a PNI's lead time), and a draw here would move the seeded + // game. They get the middle of the range instead, so a drawn figure in a quote is a typical one. + const dice=Math.random; + Math.random=()=>0.5; + let q={}; + try{ + if(spec.bind&&!spec.dom)spec.bind(args); + if(spec.quote)q=spec.quote(args)||{}; + }catch(e){apiFail(`${name}: the price could not be worked out: ${e&&e.message||e}`);}finally{Math.random=dice;for(const k of Object.keys(ui0))UI[k]=ui0[k];} + return {action:name,outcome:'quote',quote:{setup:0,monthly:0,...q,blocked:(q.blocked||[]).map(b=>apiText(String(b),400))},consistent:apiFp(spec.watch,args)===f0, + ...(spec.quote?{}:{note:'This command has no price of its own: it costs nothing up front.'})};} +// Checks shared by act and click: what no tool runs. +function apiAllowed(name,what){ + const no=apiDenied(name); + if(no)apiFail(`${name} is not available here: ${no}.`); + const kind=apiKind(name); + if(!kind||typeof ACT[name]!=='function')apiFail(what); + return kind;} +function apiRun(name,args,opts={}){ + name=String(name||''); + if(name.startsWith('view.'))name=name.slice(5); + const kind=apiAllowed(name,`There is no action "${name}". See actions or schema.`); + args=args&&typeof args==='object'&&!Array.isArray(args)?args:{}; + const spec=apiSpec(name); + if(spec){const v=apiValidate(spec,args);if(!v.ok)apiFail(`${name}: ${v.problems.join('; ')}. See schema for its arguments.`);args=v.args;} + if(kind==='game'){ + if(S&&S.lost&&name!=='closeModal')return {action:name,outcome:'stopped',reason:'The network went bankrupt: start or load another game.'}; + const w=apiWaiting(name); + if(w)return w; + if(opts.dryRun)return apiQuote(name,spec,args); + }else if(opts.dryRun)apiFail(`${name} has no price: only game commands (see schema commands) dry-run.`); + return apiDispatch(name,kind,spec,args,true);} +function apiClick(n,value){ + const b=API_LAST[n]; + if(!b)apiFail(`No button ${n} on the last screen. Call screen first.`); + if(b.disabled)apiFail(`"${b.label}" is greyed out.`); + const name=b.select||b.act,args=b.select?{v:value===undefined?undefined:String(value)}:b.args; + if(b.select&&!b.options.some(o=>o.value===args.v))apiFail(`"${b.label}" is a list: click it with a value, one of ${b.options.map(o=>JSON.stringify(o.value)).join(', ')}.`); + const kind=apiAllowed(name,`"${b.label}" runs ${name}, which is not an action.`); + if(kind==='game'){const w=apiWaiting(name);if(w)return {clicked:b.label,...w};} + return {clicked:b.label,...apiDispatch(name,kind,apiSpec(name),args,false)};} diff --git a/src/agent/70-time.js b/src/agent/70-time.js new file mode 100644 index 0000000..4f30a9d --- /dev/null +++ b/src/agent/70-time.js @@ -0,0 +1,38 @@ +/* ================= AGENT API: time ================= + The agent's clock: nothing moves until a tool asks for days with advance, one dayTick() per simulated day. */ +const apiClockDoc=()=>'Time moves only with advance: one dayTick() per simulated day, as the game loop runs it. Nothing runs between calls.'; + +// What happened since a moment (the start of an advance): the log, new incidents, cash. +// The log keeps what mattered; toasts that only repeat a log line are left out. +function apiSince({day=0,cash=0,inc=[]}={},toasts=[]){ + const seen=new Set(inc),entries=(S.log||[]).filter(e=>e.d>day).slice(-60),logged=entries.map(e=>apiNorm(apiText(e.t,400))); + const d=apiDecision(); + return {from:dateStr(day),to:dateStr(S.day),daysRun:S.day-day,cash:Math.round(S.cash),cashChange:Math.round(S.cash-cash), + newIncidents:S.inc.filter(i=>!seen.has(i.id)).map(apiIncText), + log:entries.map(e=>`${dateStr(e.d)}: ${apiText(e.t,400)}`), + toasts:[...new Set(apiToastLines(toasts))].filter(t=>{const f=apiNorm(t.replace(/^\w+: /,'').split('\n')[0]);return !logged.some(l=>l.startsWith(f));}).slice(-40), + ...(d?{decision:d,screen:apiScreen()}:{})};} + +function apiAdvanceStart(days){ + if(!S)apiFail('No game is running.'); + if(apiModalOpen())apiFail('A window is open. Answer it first (screen, click, or act closeModal), the game does not run days behind it.'); + API_SHEET=null; + apiTake(); + return {days:Math.max(1,Math.min(3650,Math.floor(+days)||1)),start:S.day,cash:S.cash,inc:S.inc.map(i=>i.id),times:[],ran:0,stop:null};} +// One day of the run; false once it is over. +function apiAdvanceDay(a){ + if(a.ran>=a.days)return false; + if(S.lost){a.stop='bankrupt';return false;} + const t=performance.now(); + dayTick(); + a.times.push({day:S.day,ms:apiR1(performance.now()-t)});a.ran++; + if(apiModalOpen()){a.stop='a window opened';return false;} + return a.ranx+t.ms,0),out=apiSince({day:a.start,cash:a.cash,inc:a.inc},apiTake()); + if(a.stop!=='a window opened'){delete out.decision;delete out.screen;} + return {from:out.from,to:out.to,daysRun:a.ran,stoppedBecause:a.stop,cash:out.cash,cashChange:out.cashChange,newIncidents:out.newIncidents,log:out.log,toasts:out.toasts, + timing:{totalMs:apiR1(total),perDayMs:apiR1(total/(a.ran||1)),slowestDays:a.times.slice().sort((x,y)=>y.ms-x.ms).slice(0,5).map(x=>({date:dateStr(x.day),ms:x.ms}))}, + ...(out.decision?{decision:out.decision,screen:out.screen}:{})};} +function apiAdvance(days){const a=apiAdvanceStart(days);while(apiAdvanceDay(a));return apiAdvanceEnd(a);} diff --git a/src/agent/90-facade.js b/src/agent/90-facade.js new file mode 100644 index 0000000..559c122 --- /dev/null +++ b/src/agent/90-facade.js @@ -0,0 +1,43 @@ +/* ================= AGENT API: the facade ================= + window.TUBES.call(tool, args) is the whole surface: one tool from API_TOOLS by name, with the MCP tool's own + arguments, answered as plain JSON. Nothing here listens, polls or runs on the day loop: toast() is only listened to + while a call runs. */ +const API_TOASTS={depth:0,list:[],real:null}; +function apiTake(){const t=API_TOASTS.list;API_TOASTS.list=[];return t;} +const apiToastLines=t=>t.map(x=>(x.kind?x.kind+': ':'')+x.text); +// toast() is a top-level function, so the game reaches it by its global name and this stands in for it. +function apiListen(on){ + if(on){if(API_TOASTS.depth++)return;const real=API_TOASTS.real=window.toast;API_TOASTS.list=[]; + window.toast=function(h,kind){API_TOASTS.list.push({kind:kind||'',text:apiText(String(h),600)});return real.apply(this,arguments);};} + else if(!--API_TOASTS.depth){window.toast=API_TOASTS.real;API_TOASTS.real=null;API_TOASTS.list=[];}} + +const API_TOOLS={ + status:()=>apiStatus(), + network:a=>apiNetwork(a.network), + city:a=>apiCity(a.city), + find:a=>apiFind(a.query,a.kind), + traceroute:a=>apiTrace(a.from,a.to), + peering_check:a=>apiPeering(a.network,a.city,a.via), + hot_spots:a=>apiHotSpots(a.limit||10), + schema:a=>apiSchema(a.section), + catalog:a=>apiCatalog(a.name), + state:a=>apiState(a.path), + results:a=>apiResults(a.path), + ui:()=>apiUi(), + actions:()=>apiActions(), + classes:()=>apiClasses(), + act:a=>{const name=a.action||a.command;if(!name)apiFail('Give action, e.g. {"action":"buildPop","args":{"city":"ams"}}.'); + return apiRun(name,a.args||{},{dryRun:!!a.dryRun});}, + screen:a=>apiScreen(a.where,a.offset), + panel:a=>apiPanel(a), + click:a=>apiClick(a.button,a.value), + open_link:a=>apiOpenLink(a.from,a.to), + advance:a=>apiAdvance(a.days), +}; +function apiCall(tool,args){ + if(typeof tool!=='string'||!own(API_TOOLS,tool))apiFail(`No tool "${tool}".`); + if(!S&&!['schema','catalog','classes','actions'].includes(tool))apiFail('No game is running.'); + apiListen(true); + try{return API_TOOLS[tool](args&&typeof args==='object'&&!Array.isArray(args)?args:{});} + finally{apiListen(false);}} +window.TUBES={version:1,tools:Object.keys(API_TOOLS),call:apiCall}; diff --git a/src/index.html b/src/index.html index 490d3db..4f7f526 100644 --- a/src/index.html +++ b/src/index.html @@ -164,6 +164,7 @@ 'use strict'; + diff --git a/tests/agent-api.test.js b/tests/agent-api.test.js new file mode 100644 index 0000000..ab7bf16 --- /dev/null +++ b/tests/agent-api.test.js @@ -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(''), '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'), '\n'); + const ship = page.assemble({ src }), dev = page.assemble({ src, dev: true }); + assert.equal(ship.html, '\n'); + assert.equal(dev.html, '\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 }); } +}); diff --git a/tests/build.test.js b/tests/build.test.js index a6c9966..ceea51a 100644 --- a/tests/build.test.js +++ b/tests/build.test.js @@ -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(/