hbengine 0.2.3

package/engine-math/pack.mjs

@@ -0,0 +1,165 @@
+/**
+ * The maths kit: a game's outcomes as weighted rows, its RTP exactly, and the
+ * pack the engine verifies (SPEC §1). A row is { weight, data, pay } where
+ * pay is { betId: multBp } (10000 = 1×, the total stake back) and data is
+ * what the bundle receives to show the round.
+ *
+ *   import { writePack, fit } from './pack.mjs';
+ *   const rows = fit(simulated, 9600);            // exact 96.00% (balance() when no row pays nothing)
+ *   writePack('math', { game: 'my-slot', rtpBp: 9600, modes: [{ id: 'base', rows, bets: ['spin'] }] });
+ *
+ * Every number here is an integer: weights are BigInt, RTP is a fraction.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_SUM = 1n << 63n;
+
+// A small seeded generator for building tables (never for play: the engine draws).
+export function rng(seed) {
+    let a = seed >>> 0;
+    const next = () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    next.int = (n) => Math.floor(next() * n);
+    return next;
+}
+
+export function binomial(n, k) {
+    let r = 1n;
+    for (let i = 1n; i <= BigInt(k); i++) r = (r * BigInt(n - k) + r * i) / i;
+    return r;
+}
+
+const gcd = (a, b) => { while (b) [a, b] = [b, a % b]; return a < 0n ? -a : a; };
+
+/** RTP of one bet over rows, exactly: { num, den } in basis points, and a 4-decimal string. */
+export function rtp(rows, bet) {
+    let num = 0n, den = 0n;
+    for (const r of rows) { den += r.weight; num += r.weight * BigInt(r.pay[bet] || 0); }
+    return { num, den, bp: bp4(num, den) };
+}
+
+export const bp4 = (num, den) => {
+    const x = (num * 10000n) / den; // bp × 10^4, truncated as the verifier reports it
+    return `${x / 10000n}.${String(x % 10000n).padStart(4, '0')}`;
+};
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp: the paying rows keep
+ * their proportions (all multiplied by one integer), the rows that pay
+ * nothing share what is left in their own proportions. Needs rows that pay
+ * nothing, and paying rows that alone return more than the target.
+ */
+export function fit(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const wins = rows.filter((r) => r.pay[bet] > 0), zeros = rows.filter((r) => !(r.pay[bet] > 0));
+    if (!zeros.length) throw new Error('fit: no row pays nothing');
+    const S = wins.reduce((s, r) => s + r.weight * (BigInt(r.pay[bet]) - T), 0n); // what the wins return above T
+    if (S <= 0n) throw new Error(`fit: the paying rows alone return less than ${targetBp / 100}%`);
+    const k = T / gcd(S, T);     // so that k·S is a multiple of T
+    const Z = (k * S) / T;       // the weight the zero rows share
+    const zw = zeros.reduce((s, r) => s + r.weight, 0n);
+    let given = 0n;
+    const out = rows.map((r) => {
+        if (r.pay[bet] > 0) return { ...r, weight: r.weight * k };
+        const w = (Z * r.weight) / zw;
+        given += w;
+        return { ...r, weight: w };
+    });
+    // The rounding remainder goes to the first zero row; a zero weight is dropped.
+    const first = out.find((r) => !(r.pay[bet] > 0));
+    first.weight += Z - given;
+    const kept = out.filter((r) => r.weight > 0n);
+    const check = rtp(kept, bet);
+    if (check.num !== T * check.den) throw new Error('fit: not exact (a bug)');
+    return kept;
+}
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp when every row pays
+ * something (a bonus buy, plinko): rows paying more than the target are
+ * all multiplied by one integer, rows paying less by another, so each
+ * group keeps its own proportions and the two balance at the target.
+ */
+export function balance(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const over = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) > T ? r.weight * (BigInt(r.pay[bet]) - T) : 0n), 0n);
+    const under = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) < T ? r.weight * (T - BigInt(r.pay[bet] || 0)) : 0n), 0n);
+    if (!over || !under) throw new Error('balance: needs rows on both sides of the target');
+    const g = gcd(over, under);
+    const out = rows.map((r) => ({ ...r, weight: r.weight * (BigInt(r.pay[bet] || 0) > T ? under / g : BigInt(r.pay[bet] || 0) < T ? over / g : 1n) }));
+    const check = rtp(out, bet);
+    if (check.num !== T * check.den) throw new Error('balance: not exact (a bug)');
+    return out;
+}
+
+/** Rows with the same data are one row with the sum of their weights. */
+export function merge(rows) {
+    const by = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify(r.data);
+        const x = by.get(key);
+        if (x) x.weight += r.weight;
+        else by.set(key, { ...r, weight: r.weight });
+    }
+    return [...by.values()];
+}
+
+// Inclusive [lo, hi] ranges of sorted indexes.
+function ranges(ids) {
+    const out = [];
+    for (const i of ids) {
+        const last = out.at(-1);
+        if (last && last[1] === i - 1) last[1] = i;
+        else out.push([i, i]);
+    }
+    return out;
+}
+
+/**
+ * Writes manifest.json and one table per mode. A mode is { id, label?, rows,
+ * bets: [id | {id, label}] }; its rows are sorted by what the first bet pays,
+ * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
+ * largest multiplier; returns them.
+ */
+export function writePack(dir, { game, rtpBp, modes }) {
+    mkdirSync(dir, { recursive: true });
+    const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
+    const report = [];
+    for (const mode of modes) {
+        const bets = mode.bets.map((b) => (typeof b === 'string' ? { id: b } : b));
+        const first = bets[0].id;
+        const rows = [...mode.rows].sort((a, b) => (a.pay[first] || 0) - (b.pay[first] || 0));
+        if (rows.length < 2 || rows.length > 1_000_000) throw new Error(`${mode.id}: 2 to 1,000,000 rows, not ${rows.length}`);
+        const sum = rows.reduce((s, r) => s + r.weight, 0n);
+        if (sum > MAX_SUM) throw new Error(`${mode.id}: weights sum to more than 2^63`);
+        const lines = rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`${mode.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            if (json.length > 4096) throw new Error(`${mode.id}: a row's data is over 4096 bytes`);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        });
+        const table = `${game}-${mode.id}.tsv`;
+        writeFileSync(join(dir, table), lines.join('\n') + '\n');
+        manifest.modes.push({
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table,
+            bets: bets.map((b) => {
+                const tiers = new Map();
+                rows.forEach((r, i) => { const m = r.pay[b.id] || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+                const { num, den, bp } = rtp(rows, b.id);
+                const hit = rows.reduce((s, r) => s + (r.pay[b.id] > 0 ? r.weight : 0n), 0n);
+                const max = Math.max(...tiers.keys());
+                report.push({ mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n });
+                return { id: b.id, ...(b.label ? { label: b.label } : {}), tiers: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) };
+            }),
+        });
+    }
+    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest) + '\n');
+    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
+    return report;
+}

package/engine-math/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/engine-math/slot.mjs

@@ -0,0 +1,94 @@
+/**
+ * A video slot for the maths kit: reels, paylines, a wild, a scatter that
+ * starts free spins (with a multiplier, retriggers), and a win cap. It plays
+ * rounds with a seeded generator to make the table's rows ("books"): every
+ * row is a whole round, base spin and free spins, with what it pays. fit()
+ * then makes the table's RTP exact; the table is the game.
+ *
+ * Pays are in basis points of the total stake (10000 = 1×) for 3, 4, 5 of a
+ * kind on a line, left to right; scatters pay anywhere, times the stake.
+ *
+ * A row's data, for the bundle: { b: spin, f: [spin…], x: free multiplier }
+ * where a spin is [stop0…stopN, winBp, lineMask, scatterCount].
+ */
+export function slot(cfg) {
+    const { reels, freeReels = reels, rows, lines, pays, wild, scatter, maxWinBp } = cfg;
+    const n = reels.length;
+
+    const grid = (strips, stops) => stops.map((s, r) => Array.from({ length: rows }, (_, y) => strips[r][(s + y) % strips[r].length]));
+
+    // One spin's wins: each line pays its best run from the left (wilds stand in).
+    function evaluate(strips, stops) {
+        const g = grid(strips, stops);
+        let win = 0, mask = 0;
+        lines.forEach((line, li) => {
+            const cells = line.map((y, r) => g[r][y]);
+            const sym = cells.find((c) => c !== wild) ?? wild;
+            if (sym === scatter.symbol) return;
+            let count = 0;
+            while (count < n && (cells[count] === sym || cells[count] === wild)) count++;
+            const pay = (pays[sym] || {})[count] || 0;
+            // A run of wilds alone pays as wilds when that is more.
+            let wc = 0;
+            while (wc < n && cells[wc] === wild) wc++;
+            const best = Math.max(pay, (pays[wild] || {})[wc] || 0);
+            if (best > 0) { win += best; mask |= 1 << li; }
+        });
+        const scatters = g.flat().filter((c) => c === scatter.symbol).length;
+        win += (scatter.pays[scatters] || 0);
+        return { win, mask, scatters };
+    }
+
+    const spin = (strips, next) => strips.map((s) => next.int(s.length));
+
+    /** One whole round: the row's data and what it pays (bp of the stake).
+     * A bought round is the free spins alone, as three scatters start them. */
+    function round(next, buy = false) {
+        const stops = buy ? null : spin(reels, next);
+        const base = buy ? { win: 0, scatters: 3 } : evaluate(reels, stops);
+        const data = buy ? { buy: 1 } : { b: [...stops, base.win, base.mask, base.scatters] };
+        let total = base.win;
+        let left = scatter.spins[base.scatters] || 0;
+        if (left) {
+            data.f = [];
+            data.x = scatter.multiplier;
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const s = spin(freeReels, next);
+                const e = evaluate(freeReels, s);
+                data.f.push([...s, e.win * scatter.multiplier, e.mask, e.scatters]);
+                total += e.win * scatter.multiplier;
+                left += scatter.retrigger[e.scatters] || 0;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { evaluate, round, grid };
+}
+
+/**
+ * Plays `count` rounds (bought ones with `buy`) and keeps them as rows: every paying round, and up to
+ * `losing` different losing rounds that share the weight of every losing
+ * round played (so the rows keep the played RTP and hit rate before fit).
+ */
+export function books(game, next, count, losing = 4000, buy = false) {
+    const wins = new Map(), lose = new Map();
+    let lost = 0n;
+    for (let i = 0; i < count; i++) {
+        const { data, pay } = game.round(next, buy);
+        if (pay <= 0) {
+            lost++;
+            if (lose.size < losing) lose.set(JSON.stringify(data), { weight: 0n, data, pay: { spin: 0 } });
+            continue;
+        }
+        const key = JSON.stringify(data);
+        const r = wins.get(key);
+        if (r) r.weight += 1n;
+        else wins.set(key, { weight: 1n, data, pay: { spin: pay } });
+    }
+    const zeros = [...lose.values()];
+    zeros.forEach((r, i) => { r.weight = lost / BigInt(zeros.length) + (BigInt(i) < lost % BigInt(zeros.length) ? 1n : 0n); });
+    return [...zeros.filter((r) => r.weight > 0n), ...wins.values()];
+}

package/engine-math/tumble.mjs

@@ -0,0 +1,94 @@
+/**
+ * A tumbling, scatter-pays slot for the maths kit: a cols × rows grid, every
+ * cell drawn by symbol weight; a symbol pays when enough of it is anywhere
+ * on the grid; winners vanish, the rest fall, new symbols drop in, until
+ * nothing pays. Scatters start free spins, where multiplier symbols land
+ * and multiply the spin's win. Like slot.mjs, it plays whole rounds into
+ * rows; fit() then makes the RTP exact.
+ *
+ * Symbols are single characters. Pays are basis points of the stake by
+ * count: { A: [[8, 2000], [10, 5000], [12, 10000]] } pays the highest band
+ * the count reaches.
+ *
+ * A row's data, for the page:
+ *   { b: spin, f: [spin…] }   spin = [grid, [tumble…], multipliers?]
+ *   grid    the first grid, column by column, top to bottom ("ABCDE…")
+ *   tumble  [winners, winBp, fill0, fill1, …]: the symbols that paid, what
+ *           they paid, and per column the new symbols that drop in (top first)
+ *   multipliers  free spins only: the values of the multiplier symbols on the
+ *           last grid, summed onto the spin's win when it won
+ */
+export function tumble(cfg) {
+    const { cols, rows, weights, freeWeights = weights, pays, scatter, bomb, maxWinBp } = cfg;
+    const pick = (w, next) => {
+        const total = w.reduce((s, [, n]) => s + n, 0);
+        let x = next() * total;
+        for (const [s, n] of w) if ((x -= n) < 0) return s;
+        return w[w.length - 1][0];
+    };
+    const table = (o) => Object.entries(o);
+    const base = table(weights), free = table(freeWeights);
+    const counts = Object.keys(scatter.spins).map(Number), least = Math.min(...counts), most = Math.max(...counts);
+
+    // One spin: the grid, its tumbles, and (free spins) its multipliers.
+    function spin(next, inFree) {
+        const w = inFree ? free : base;
+        const draw = () => {
+            const s = pick(w, next);
+            return s === bomb?.symbol && !inFree ? pick(base.filter(([x]) => x !== bomb.symbol), next) : s;
+        };
+        let grid = Array.from({ length: cols }, () => Array.from({ length: rows }, draw));
+        const first = grid.map((c) => c.join('')).join('');
+        const tumbles = [];
+        let win = 0;
+        for (;;) {
+            const counts = {};
+            for (const c of grid) for (const s of c) counts[s] = (counts[s] || 0) + 1;
+            let paid = '', bp = 0;
+            for (const [s, bands] of Object.entries(pays)) {
+                const band = bands.filter(([n]) => counts[s] >= n).at(-1);
+                if (band) { paid += s; bp += band[1]; }
+            }
+            if (!paid) break;
+            win += bp;
+            const fills = grid.map((c) => {
+                const kept = c.filter((s) => !paid.includes(s));
+                const add = Array.from({ length: rows - kept.length }, draw);
+                c.splice(0, rows, ...add, ...kept); // new symbols on top
+                return add.join('');
+            });
+            tumbles.push([paid, bp, ...fills]);
+        }
+        const out = [first, tumbles];
+        const scatters = grid.flat().filter((s) => s === scatter.symbol).length; // on the last grid
+        let total = win;
+        if (inFree && bomb) {
+            const bombs = grid.flat().filter((s) => s === bomb.symbol).map(() => pick(bomb.values, next));
+            if (bombs.length) out.push(bombs);
+            if (win && bombs.length) total = win * bombs.reduce((a, b) => a + b, 0);
+        }
+        return { out, total, scatters };
+    }
+
+    /** One whole round: the row's data and what it pays (bp of the stake). */
+    function round(next) {
+        const b = spin(next, false);
+        const data = { b: b.out };
+        let total = b.total + (scatter.pays[Math.min(b.scatters, most)] || 0);
+        let left = b.scatters >= least ? scatter.spins[Math.min(b.scatters, most)] : 0;
+        if (left) {
+            data.f = [];
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const f = spin(next, true);
+                data.f.push(f.out);
+                total += f.total;
+                if (f.scatters >= scatter.retrigger.count) left += scatter.retrigger.spins;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { round };
+}

package/engine-mcp/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/engine-mcp/server.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * The House Engine MCP server: hbengine's commands as tools, so an agent
+ * (Claude Code, Cursor, …) builds, verifies and ships a studio game without
+ * leaving its editor. Stdio JSON-RPC, the Model Context Protocol 2024-11-05
+ * subset every client speaks: initialize, tools/list, tools/call. No
+ * dependencies: each tool runs hbengine and returns what it printed.
+ *
+ *   { "mcpServers": { "house-engine": { "command": "node", "args": ["…/engine-mcp/server.mjs"],
+ *       "env": { "HBENGINE_KEY": "hbk_…" } } } }
+ *
+ * With HBENGINE_KEY the uploads and numbers go through the studio platform
+ * (the key from the dashboard's Developer page); without it, the local pipeline.
+ *
+ * Run as a file it serves; imported (hbengine mcp, the tests) it exports
+ * run, handle and serve.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { pathToFileURL } from 'node:url';
+import { TEMPLATES } from '../engine-cli/templates.mjs';
+
+
+// The version a client sees in serverInfo: the published package's
+// (hbengine/package.json, one level up in the npm layout), else this
+// package's own, so a client never reads a number the build did not set.
+const VERSION = (() => {
+    for (const rel of ['../package.json', './package.json']) {
+        try {
+            const v = JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8')).version;
+            if (typeof v === 'string' && v) return v;
+        } catch { /* the next candidate */ }
+    }
+    return 'dev';
+})();
+const HBENGINE = new URL('../engine-cli/hbengine.mjs', import.meta.url).pathname;
+const GUIDE = new URL('../engine-sdk/GUIDE.md', import.meta.url).pathname;
+const DIR = { type: 'string', description: 'the project directory (math/, bundle/, hbengine.json)' };
+// The most a reply to the reviewer may say (the studio platform refuses more).
+export const REPLY_MAX = 4000;
+// The most one support message may say (the same).
+export const TICKET_MAX = 8000;
+
+export const TOOLS = [
+    { name: 'engine_connect', description: 'Link this machine to the developer\'s studio on House Studio: opens the studio dashboard in their browser, they press Approve, and the key is kept on this machine for every other tool. Ask the developer for their studio slug (dashboard, Organisation, Profile) first. Waits up to ten minutes for the approval.', inputSchema: { type: 'object', properties: { studio: { type: 'string', description: 'the studio slug, as the dashboard shows it' } }, required: ['studio'] } },
+    { name: 'engine_guide', description: 'The guide to building a House Engine game: math pack, bundle, SDK, panel, currencies, languages, what the upload checks. Read it first.', inputSchema: { type: 'object', properties: {} } },
+    { name: 'engine_templates', description: 'The templates a game can start from, with what each one is.', inputSchema: { type: 'object', properties: {} } },
+    { name: 'engine_init', description: 'Start a game from a template: math/, bundle/, hbengine.json in a new directory.', inputSchema: { type: 'object', properties: { dir: { type: 'string', description: 'new directory' }, template: { type: 'string', enum: Object.keys(TEMPLATES) }, slug: { type: 'string', description: 'the game slug, a-z 0-9 -, 2–24 chars' } }, required: ['dir', 'slug'] } },
+    { name: 'engine_verify', description: 'Verify the math pack with the engine’s own verifier: exact RTP, hit rate and max multiplier per bet, the mathHash; or the errors.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_lint', description: 'Scan the bundle as the upload will: budgets, assets.json, forbidden code, outside URLs, engine use.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_test', description: 'Offline: the upload\'s checks (boot, idle, fit at desktop and phone sizes and fullscreen, a bet through the game\'s own UI, currency, errors, network) in Chrome against engine-dev, the engine on this machine. Needs Chrome and playwright-core. About two minutes.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_pack', description: 'Verify and lint, then write dist/<slug>-<date>.tgz (math, bundle, store page, tile) and its sha256: the file to hand to Housebets.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_upload', description: 'Ship a version: verify + lint, upload to the portal, which registers it with the sandbox and plays the conformance run on desktop and phone (bet, currency, outage, fit, errors, network). Returns the report and, on success, the link to play it inside the site. Takes about two minutes.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_status', description: 'Every version of the game and its state (uploaded, verified, sandbox, failed), its review (in review, approved, returned) and which is live, and the game\'s state on the studio platform.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_store', description: 'Send the store page from store.json in the project (title, category, description, features, tags, languages, rules per language; tile.png or tile.webp, 3:4, if present). Answers what review still needs. On a live game the tile stays the reviewed one until Housebets reset it; the page is saved all the same. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_submit', description: 'Submit the newest version that passed every check for review by Housebets. Needs the studio agreement (accepted by an owner in the dashboard), a complete store page and HBENGINE_KEY. Housebets emails the verdict; once approved, engine_live puts it live.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_live', description: 'Put the newest approved version live, as an owner pressing Make live on the game\'s page: the round server and the front end switch to it within seconds. Only after Housebets approved it (engine_status shows "approved"; the studio gets an email). Going live is an owner\'s: the key must be one an owner of the studio made. The first time, players find the game on Housebets once Housebets switches its catalogue page on. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_preflight', description: 'Before engine_submit: the review checklist items a machine can check on the newest version (the RTP and max win the rules quote against the verified maths, rules in every store language, the store page, fit on phone and desktop, recovery from errors, load, the network and the scan), each pass / fail with the reason, and the exact facts the rules must quote. Fix every failure first; a reviewer would send it back. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_review', description: 'Housebets\' review of the game, like a pull request: every thread (must-fix or suggestion, the area, the version it was raised on, open / fixed / resolved) with the conversation, and the review checklist results. Fix every open must-fix thread in the project, then engine_upload and engine_submit: submitting marks the open must-fix threads fixed in that version, and Housebets checks each. Use engine_reply only to ask the reviewer a question or explain a choice. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_reply', description: `Ask the reviewer a question on a review thread, or explain a change or a choice, in at most ${REPLY_MAX} characters. Fixes themselves go in by uploading and submitting (engine_upload, engine_submit). Needs HBENGINE_KEY.`, inputSchema: { type: 'object', properties: { dir: DIR, thread: { type: 'integer', description: 'the thread id from engine_review' }, message: { type: 'string', description: `your question, or what you changed and why (at most ${REPLY_MAX} characters)` }, fixed: { type: 'boolean', description: 'only when the change is already in a version you uploaded but have not submitted yet; engine_submit marks fixes itself' } }, required: ['dir', 'thread', 'message'] } },
+    { name: 'engine_stats', description: 'The game\'s play in the last 30 days by coin: rounds, turnover, GGR, actual RTP against the maths\' expected band, and the shell\'s counts of launches, errors and rounds left open. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_feedback', description: `Send Housebets a support ticket or feedback: a bug in the engine, the SDK, hbengine or these tools; a question the guide does not answer; an idea; or what the developer thinks of House Engine. Use it when something of House Engine (not the developer's own game) is broken or unclear after reading engine_guide, or when the developer asks to send feedback. Say what you did, what happened, what you expected, and the exact error text; never include a key or a password. hbengine's version, node, the OS and the game in dir go with it. Housebets answers by email and in engine_tickets. With ticket, adds to that ticket instead (close: true when it is solved). Needs HBENGINE_KEY.`, inputSchema: { type: 'object', properties: { message: { type: 'string', description: `what happened, what you expected, the exact error (at most ${TICKET_MAX} characters)` }, kind: { type: 'string', enum: ['bug', 'question', 'idea', 'feedback'], description: 'what it is (default feedback)' }, subject: { type: 'string', description: 'one line; empty, the message\'s first line' }, dir: { type: 'string', description: 'the project directory, when it is about a game' }, ticket: { type: 'integer', description: 'a ticket id from engine_tickets, to add to it' }, close: { type: 'boolean', description: 'with ticket: close it, it is solved' } }, required: ['message'] } },
+    { name: 'engine_tickets', description: 'The studio\'s support tickets and Housebets\' answers: each open one with its whole conversation. Answer one with engine_feedback and its ticket id. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: {} } },
+];
+
+export function run(tool, a) {
+    if (tool === 'engine_templates') return { text: Object.entries(TEMPLATES).map(([t, about]) => `${t}: ${about}`).join('\n'), status: 0 };
+    if (tool === 'engine_connect') {
+        if (typeof a.studio !== 'string' || !/^[a-z0-9][a-z0-9-]{1,47}$/.test(a.studio)) return { text: 'studio is required: the slug the dashboard shows (Organisation, Profile)', status: 1 };
+        const r = spawnSync('node', [HBENGINE, 'connect', '--studio', a.studio], { encoding: 'utf8', timeout: 11 * 60 * 1000, stdio: ['ignore', 'pipe', 'pipe'] });
+        if (r.error) return { text: `hbengine did not run: ${r.error.message}`, status: 1 };
+        return { text: ((r.stdout || '') + (r.stderr || '')).trim() || (r.status === 0 ? 'connected' : `exit ${r.status ?? 1}`), status: r.status ?? 1 };
+    }
+    if (tool === 'engine_feedback' || tool === 'engine_tickets') return support(tool, a);
+    if (typeof a.dir !== 'string' && tool !== 'engine_guide') return { text: 'dir is required', status: 1 };
+    if (tool === 'engine_init' && typeof a.slug !== 'string') return { text: 'slug is required', status: 1 };
+    if (tool === 'engine_init' && a.template && !TEMPLATES[a.template]) return { text: `template: one of ${Object.keys(TEMPLATES).join(', ')}`, status: 1 };
+    // Refused here, before hbengine and the platform see it, with the count the agent can act on.
+    if (tool === 'engine_reply' && typeof a.message === 'string' && a.message.length > REPLY_MAX) return { text: `the reply is over ${REPLY_MAX} characters (${a.message.length}): say less, or split it over two replies`, status: 1 };
+    if (tool === 'engine_guide') {
+        return { text: readFileSync(GUIDE, 'utf8'), status: 0 };
+    }
+    const args = tool === 'engine_init' ? ['init', a.dir, '--template', a.template || 'coin', '--slug', a.slug]
+        : tool === 'engine_reply' ? ['reply', a.dir, '--thread', String(a.thread), '--message', String(a.message || ''), ...(a.fixed ? ['--fixed'] : [])]
+        : [tool.slice('engine_'.length), a.dir];
+    const r = spawnSync('node', [HBENGINE, ...args], { encoding: 'utf8', timeout: 10 * 60 * 1000 });
+    // hbengine did not run at all (not found, killed at the timeout): say so, not "nullnull".
+    if (r.error) return { text: `hbengine did not run: ${r.error.message}`, status: 1 };
+    return { text: ((r.stdout || '') + (r.stderr || '')).trim() || (r.status === 0 ? 'ok' : `exit ${r.status ?? 1}`), status: r.status ?? 1 };
+}
+
+// Support: hbengine feedback / tickets, told it is an agent asking (the ticket says so).
+function support(tool, a) {
+    let args = ['tickets'];
+    if (tool === 'engine_feedback') {
+        const message = typeof a.message === 'string' ? a.message : '';
+        if (!message.trim() && !(a.ticket && a.close)) return { text: 'message is required: what happened, what you expected, the exact error', status: 1 };
+        if (message.length > TICKET_MAX) return { text: `the message is over ${TICKET_MAX} characters (${message.length}): put the essentials first, or send the rest on the ticket`, status: 1 };
+        if (a.kind !== undefined && !['bug', 'question', 'idea', 'feedback'].includes(a.kind)) return { text: 'kind: one of bug, question, idea, feedback', status: 1 };
+        if (a.ticket !== undefined && !Number.isInteger(a.ticket)) return { text: 'ticket: the number engine_tickets shows', status: 1 };
+        args = ['feedback', ...(typeof a.dir === 'string' ? [a.dir] : []), '--message', message];
+        if (a.ticket !== undefined) args.push('--ticket', String(a.ticket), ...(a.close ? ['--close'] : []));
+        else args.push('--kind', a.kind || 'feedback', ...(typeof a.subject === 'string' && a.subject ? ['--subject', a.subject] : []));
+    }
+    const r = spawnSync('node', [HBENGINE, ...args], { encoding: 'utf8', timeout: 2 * 60 * 1000, env: { ...process.env, HBENGINE_VIA: 'mcp' } });
+    if (r.error) return { text: `hbengine did not run: ${r.error.message}`, status: 1 };
+    return { text: ((r.stdout || '') + (r.stderr || '')).trim() || (r.status === 0 ? 'ok' : `exit ${r.status ?? 1}`), status: r.status ?? 1 };
+}
+
+const error = (text) => ({ content: [{ type: 'text', text }], isError: true });
+
+/** One request's result (null for a notification, or for a line that is not a request), the same whatever the transport. */
+export function handle(msg) {
+    if (!msg || typeof msg !== 'object') return null;
+    const { id, method } = msg;
+    // `params` may be missing, null or a scalar from a loose client: an empty one, never a crash.
+    const params = msg.params && typeof msg.params === 'object' ? msg.params : {};
+    if (method === 'initialize') return { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'house-engine', version: VERSION } };
+    if (method === 'tools/list') return { tools: TOOLS };
+    if (method === 'tools/call') {
+        const tool = TOOLS.find((t) => t.name === params.name);
+        if (!tool) return error(`no tool ${params.name}`);
+        // A tool that throws answers its own call; the server stays up for the next.
+        try {
+            const result = run(tool.name, params.arguments && typeof params.arguments === 'object' ? params.arguments : {});
+            return { content: [{ type: 'text', text: result.text }], isError: result.status !== 0 };
+        } catch (e) {
+            return error(`${params.name} failed: ${e && e.message ? e.message : String(e)}`);
+        }
+    }
+    return id !== undefined ? {} : null;
+}
+
+/** Serves JSON-RPC over a pair of streams (stdio by default). No line can end the server: a
+ * request it cannot handle is answered with a JSON-RPC error, anything else is dropped. */
+export function serve({ input = process.stdin, output = process.stdout } = {}) {
+    const send = (body) => output.write(JSON.stringify({ jsonrpc: '2.0', ...body }) + '\n');
+    createInterface({ input }).on('line', (line) => {
+        let msg;
+        try { msg = JSON.parse(line); } catch { return; }
+        try {
+            const result = handle(msg);
+            if (result !== null) send({ id: msg.id, result });
+        } catch (e) {
+            if (msg && typeof msg === 'object' && msg.id !== undefined) send({ id: msg.id, error: { code: -32603, message: e && e.message ? e.message : String(e) } });
+        }
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) serve();