seriesoftubes/src/agent/30-docs.js
Frederic Jung 32b0b282f8
Bulk actions for the late game: POP standards, kit everywhere, buy on signing, network search
- POP standards by kind (micro, medium, regional hub), one button per POP and one per kind in Utilities (#315)
- Redundancy kit at every POP from Utilities, and in the intern's template (#317)
- Offers that need a generator, second router or second site can buy it and sign (#241)
- The intern's Light more fiber order can leave new fiber dark (#316)
- Search and connected-only filter for a POP's transit, exchange, PNI and cache lists (#199)
- The link panel moves on to the next parallel link after a decommission (#119)
2026-11-10 07:03:57 +00:00

164 lines
16 KiB
JavaScript

/* ================= 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 a normal game signed when it started: global | boutique | broker. chartSet is false until one is signed.'},
baronWon:{type:'number',doc:'The day a broker won Glass Baron, or 0.'},
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 (te: the day the term ends, mk: the bandwidth market it was priced in, hag: an open renewal haggle {rate, until}).'},
offers:{type:'array',doc:'Pending customer offers, each expiring on a day (mk: the bandwidth market they were priced in; refN: the customer who referred them).'},
sales:{type:'map',doc:'The sales desk: p (eng, shark, ceo or null), hired (day), vp (the day a VP of Sales takes over from the CEO), golf and say (the CEO\'s next golf deal and opinion). Offers and customers carry by: who brought or signed them, orbit ones too (the shark\'s may carry the skyfull promise).'},
slAuto:{type:'map',doc:'Deals the sales desk signs for you (only while someone runs sales): on (sign offers that fit), min (decline offers paying less a month; 0 never), ren (answer renewal haggles), wk (this week: w, p who was at the desk, n signed, rev their monthly revenue, x declined, y declined but signed anyway by the CEO) and rep (last week, the same).'},
cl:{type:'map',doc:'Customer lifecycle (#178): odd (the day of the last unusual departure) and mo, one entry a month of customers won, renewed, grown, haggling and lost by reason.'},
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.'},
pieV:{type:'number',doc:'Pie in the Sky version stamp: 1 in games started since it shipped (only those unlock it, on a Tier 1 win).'},
pie:{type:'map',doc:'The rocket company (Pie in the Sky), or null: company, factory, stock, pads, crusts (cohorts of pies by launch day), dishes, landing rights (lic), launch queue (q), R&D, spats, the founder (posts, promises made and broken with their due days, and his antics: jit, the market jitters 0..1 that fade over 30 days and lower orbit offer odds and happiness; next, the day of the next antic; kid, 1 + the index of PIE_KIDS once he has named his son; bill, the day orbit billing comes back (no orbit income until then); nerv, hype, leak: days a posting spree, Mars hype and a leaked launch date (dearer launch insurance) last until; mars, the due day of the Mars promise, whose slip loses a few orbit customers; all only with chaos on), books, and government money (gov: auctions, awards, Ex-Im).'},
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 (network work only: deals belong to the sales desk, slAuto), 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.'},
popTiers:{type:'map',doc:'POP standards by kind: def.micro|medium|hub is {g: router model, rt: routers} or null; at maps a POP city to its kind.'},
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.'},
cm:{type:'map',doc:'The capacity market (Lambda Bazaar): hold (% of every fiber never sold, kept for your own traffic), p (per product spec/w100/w400/w800/w1600/iru: on, min demand, floor % of list), off (routes the broker leaves alone, by "a|b"), sh (market shocks: why, from, until, m multiplier, on a route k, a city c or every subsea route), news (the latest market news), seen (incident ids already turned into news).'},
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.'},
vol:{type:'number',doc:'Traffic carried in this game, in petabytes (each day adds a day of what was served); badges at 1 PB, 100 PB, 1 EB and 1 ZB.'},
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={
pie:{type:'map',doc:'Orbit this compute (only with a rocket company): revenue (rev; 0 while the founder has orbit billing down, with billOff what it would have been; including patchy: {mo, cr} from patchy-sky customers who pay from 10% coverage, before a crust carries anything, and fade out between 40% and 60%), service per orbit customer, landing dishes, flows through the sky, backhaul for cut-off POPs (bh), crust and dish load, government money (gov).'},
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.'},
};
/* The dice rather than the board: in the player's tab (over the relay) state never returns these, and schema says why.
The MCP server's own page returns them, for debugging. */
const API_WITHHELD={
rng:'the seed: it predicts every future random draw',
nextFail:'the day the next failure fires',
nextEvent:'the day the next world event fires',
'scn.nextDdos':'the day of the next scripted attack in a scenario',
};