@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/mcp/server.js

@@ -0,0 +1,330 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { ACTIVITY_WORDS, setActivity } from "../status/status.js";
+import { COMPOSE_DIR } from "../compose/contract.js";
+import { ADS_BRIEF, ADS_OUT } from "../compose/variations.js";
+import { hostedFromApi } from "./hosted.js";
+import { localIds, withModels } from "./models.js";
+import { currentVersion } from "../update.js";
+export const PROTOCOL = '2025-06-18';
+const MAX_IMAGE_BYTES = 1_500_000;
+const MAX_IMAGES = 4;
+const PICTURE_DIRS = [join('design', 'first-look'), join('design', 'shots'), join('design', 'look'), join('.funtools', 'capture'), join('.funtools', 'reel')];
+const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+export const RUN_ALLOWED = new Set([
+    'flow', 'find', 'check', 'verify', 'test', 'sim', 'capture', 'compare', 'score', 'play', 'playtest', 'assets', 'gen', 'estimate', 'job', 'jobs',
+    'note', 'progress', 'reel', 'trailer', 'compose', 'look', 'feel', 'boxes', 'life', 'walk', 'world', 'reach', 'depth', 'hook', 'scene', 'inspect',
+    'audit-screens', 'mobile-qa', 'profile', 'loudness', 'zero', 'review', 'motion', 'optimize', 'model', 'cut', 'character', 'cast', 'firstlook', 'gdd', 'spec', 'rooms',
+    'wow', 'variety', 'decide', 'smoke', 'pack', 'doctor', 'usage', 'whoami', 'greenlight', 'pitch', 'owner', 'lanes', 'pick', 'feedback',
+    'store',
+]);
+const dirProp = { dir: { type: 'string', description: 'The game folder (absolute, or relative to where the server started). Default: that folder.' } };
+const str = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+const opt = (flag, v) => (str(v) ? [flag, String(v)] : typeof v === 'number' ? [flag, String(v)] : []);
+const yes = (flag, v) => (v === true ? [flag] : []);
+const composition = (a) => str(a.composition) ?? join(COMPOSE_DIR, `${str(a.starter) ?? 'trailer'}.html`);
+export const TOOLS = [
+    { name: 'flow', description: 'Where the game is and the one next step, with the exact tool to call and why. Call it at the start of every turn.', props: { ...dirProp }, argv: () => ['flow'] },
+    { name: 'find', description: 'Search the kit in plain words: the skills to read and the commands to run for what you want to do, best first.', props: { ...dirProp, ask: { type: 'string', description: 'What you want to do, in plain words.' } }, required: ['ask'], argv: (a) => ['find', String(a.ask ?? '')] },
+    { name: 'flow_start', description: 'Make a new game from the confirmed brief (its title, kind and length are read from the line). Asks nothing.', props: { ...dirProp, idea: { type: 'string', description: 'The brief in one line.' }, name: { type: 'string', description: 'The title.' }, framework: { type: 'string', enum: ['pixi', 'three-world', 'three'] } }, required: ['idea'], argv: (a) => ['flow', 'start', '.', '--idea', String(a.idea), ...opt('--name', a.name), ...opt('--framework', a.framework)], timeoutMs: 600_000 },
+    { name: 'flow_ask', description: 'Put the plan to the owner: readies the question with the plan\'s price and what it still owes, for you to show in the chat.', props: { ...dirProp }, argv: () => ['flow', 'ask'] },
+    { name: 'flow_agree', description: 'Record the owner\'s yes to the plan, in their words. Only after they said it in the chat.', props: { ...dirProp, words: { type: 'string', description: 'The owner\'s own words.' } }, required: ['words'], argv: (a) => ['flow', 'agree', '--by', 'owner', String(a.words)] },
+    { name: 'flow_round', description: 'Close a build round on its evidence (exit 1 names what is missing).', props: { ...dirProp }, argv: () => ['flow', 'round'] },
+    { name: 'flow_look', description: 'The whole-game look, when the flow says it is due: writes its brief (would you ship this today?) for a fresh agent; once it is filed, routes each defect to its owner. Never vetoes.', props: { ...dirProp }, argv: () => ['flow', 'look'] },
+    { name: 'check', description: 'Build, the rules suite and verify through the real Play button, in one call.', props: { ...dirProp, phone: { type: 'boolean', description: 'Also verify on a phone viewport.' } }, argv: (a) => ['check', ...yes('--phone', a.phone)], timeoutMs: 900_000 },
+    { name: 'verify', description: 'Run the game probe locally; writes verify.json.', props: { ...dirProp, viewport: { type: 'string', enum: ['desktop', 'phone', 'both'] } }, argv: (a) => ['verify', ...opt('--viewport', a.viewport)], timeoutMs: 900_000 },
+    { name: 'test', description: 'The game\'s own tests, recorded for the flow.', props: { ...dirProp }, argv: () => ['test'], timeoutMs: 600_000 },
+    { name: 'sim', description: 'The rules played by the GDD\'s bots (seeded); the naive bot must be able to lose.', props: { ...dirProp }, argv: () => ['sim'], timeoutMs: 600_000 },
+    { name: 'capture', description: 'Capture the built game at a view (or every view); the pictures come back.', props: { ...dirProp, view: { type: 'string' }, all: { type: 'boolean' }, viewport: { type: 'string', enum: ['desktop', 'phone'] } }, argv: (a) => ['capture', ...(a.all === true ? ['--all'] : opt('--view', a.view)), ...opt('--viewport', a.viewport)], timeoutMs: 600_000 },
+    { name: 'compare', description: 'Set captures beside their target frames; names the biggest difference.', props: { ...dirProp, target: { type: 'string', description: 'The target picture(s), comma-separated.' }, view: { type: 'string' } }, required: ['target'], argv: (a) => ['compare', '.', '--target', String(a.target), ...opt('--view', a.view)], timeoutMs: 600_000 },
+    { name: 'score', description: 'Score a view against its target frame (0-100; the bar is 75); --fixes lists the moves.', props: { ...dirProp, target: { type: 'string' }, view: { type: 'string' }, fixes: { type: 'boolean' } }, argv: (a) => (a.fixes === true ? ['score', '.', '--fixes'] : ['score', '.', ...opt('--target', a.target), ...opt('--view', a.view)]), timeoutMs: 600_000 },
+    { name: 'assets_script', description: 'Turn the GDD\'s ## Asset script into the game\'s asset list (write=true writes it).', props: { ...dirProp, write: { type: 'boolean' } }, argv: (a) => ['assets', 'script', ...yes('--write', a.write)] },
+    { name: 'assets_gen', description: 'Make the planned assets into public/assets/ (dry_run=true shows the prompts and the price).', props: { ...dirProp, dry_run: { type: 'boolean' }, only: { type: 'string' } }, argv: (a) => ['assets', 'gen', ...yes('--dry-run', a.dry_run), ...opt('--only', a.only), ...(a.dry_run === true ? [] : ['--yes'])], timeoutMs: 1_800_000 },
+    { name: 'assets_process', description: 'Trim and size the made assets and write their URLs.', props: { ...dirProp }, argv: () => ['assets', 'process'] },
+    { name: 'gen', description: 'One generation job (image, sprite, sound, music, model3d, skybox…), saved into the game; unity names a Unity project, whose Assets/_Game/Generated/ it goes into, ready to import.', props: { ...dirProp, kind: { type: 'string' }, prompt: { type: 'string' }, out: { type: 'string' }, unity: { type: 'string', description: 'A Unity project folder (absolute).' } }, required: ['kind', 'prompt'], argv: (a) => ['gen', String(a.kind), String(a.prompt), ...opt('--out', a.out), ...opt('--unity', a.unity), '--yes'], timeoutMs: 1_800_000 },
+    { name: 'note_add', description: 'Record the owner\'s words as a note the build answers; hold: true when the owner holds the stage ("keep designing, do not build yet"), shown as waiting on them and never closed by an agent.', props: { ...dirProp, words: { type: 'string' }, hold: { type: 'boolean' } }, required: ['words'], argv: (a) => ['note', 'add', String(a.words), '--by', 'owner', ...(a.hold === true ? ['--hold'] : [])] },
+    { name: 'note_verdict', description: 'Record the owner\'s verdict on a note or a stage (e.g. stage "prototype": the first playable has potential; "chapter:c2").', props: { ...dirProp, what: { type: 'string' }, says: { type: 'string', enum: ['accept', 'reject'] }, words: { type: 'string' } }, required: ['what', 'says'], argv: (a) => ['note', 'verdict', String(a.what), String(a.says), ...(str(a.words) ? [String(a.words)] : [])] },
+    { name: 'progress_card', description: 'Record a round with a frame of the build (shot "last" = the newest capture).', props: { ...dirProp, line: { type: 'string' }, stage: { type: 'string' }, shot: { type: 'string' }, next: { type: 'string' } }, required: ['line'], argv: (a) => ['progress', 'card', '--line', String(a.line), ...opt('--stage', a.stage), ...opt('--shot', a.shot), ...opt('--next', a.next)] },
+    { name: 'reel', description: 'A short clip of real play (MP4 in .funtools/reel/), for a reveal.', props: { ...dirProp, seconds: { type: 'number' }, viewport: { type: 'string', enum: ['desktop', 'phone'] } }, argv: (a) => ['reel', '.', ...opt('--seconds', a.seconds), ...opt('--viewport', a.viewport)], timeoutMs: 900_000 },
+    {
+        name: 'compose_video',
+        description: 'A trailer, a 9:16 post or a playable ad\'s end card as an HTML composition (HyperFrames: timed clips on tracks, GSAP titles, the game\'s own sound) with the game itself as a live clip, rendered to an MP4 locally and deterministically. starter writes design/compose/<starter>.html from the game\'s build, key art, captures and sound when there is none yet; edit its words and timings and call again. Returns the MP4 path and a contact sheet of 12 frames: look at it before using the video.',
+        props: {
+            ...dirProp,
+            composition: { type: 'string', description: 'The composition, relative to the game folder (default design/compose/<starter>.html).' },
+            starter: { type: 'string', enum: ['trailer', 'post', 'endcard'], description: 'Write this starter first when the composition does not exist (trailer 15 s 16:9, post 10 s 9:16, endcard 6 s 9:16).' },
+            aspect: { type: 'string', enum: ['16:9', '9:16', '1:1'] },
+            seconds: { type: 'number', description: 'The length, 1 to 120 s.' },
+            quality: { type: 'string', enum: ['draft', 'standard', 'high'] },
+        },
+        argv: (a) => ['compose', 'render', composition(a), ...opt('--aspect', a.aspect), ...opt('--seconds', a.seconds), ...opt('--quality', a.quality)],
+        timeoutMs: 1_800_000,
+    },
+    {
+        name: 'ad_variations',
+        description: 'Ad cuts from one brief, for a store test or a network A/B: design/compose/ads.json names the hooks (each a first-second line and the capture or view it opens on), the calls to action, the lengths, the aspects, the end card and max (default 12). Makes at most max of the cross product, every hook, call to action, length and aspect in a cut before any pair repeats, each its own composition from the post or trailer starter, rendered locally like compose_video on one staged game. Writes .funtools/compose/ads/<id>/ (MP4, contact sheet, record), index.json (each cut\'s verdict and checks) and sheet.png (a labelled frame per cut), which comes back as a picture. An end card unlike the playable\'s own words is a warning, never a refusal. dry_run plans without rendering. The person picks which cut to publish.',
+        props: {
+            ...dirProp,
+            brief: { type: 'string', description: `The brief, relative to the game folder (default ${ADS_BRIEF}).` },
+            max: { type: 'number', description: 'The most cuts, over the brief\'s own max (1 to 60).' },
+            dry_run: { type: 'boolean', description: 'Print the plan (which cuts, what each opens on) and render nothing.' },
+            quality: { type: 'string', enum: ['draft', 'standard', 'high'] },
+        },
+        argv: (a) => ['compose', 'variations', ...(str(a.brief) ? [String(a.brief)] : []), ...opt('--max', a.max), ...yes('--dry-run', a.dry_run), ...opt('--quality', a.quality)],
+        timeoutMs: 3_600_000,
+    },
+];
+const EXTRA = [
+    { name: 'dev', description: 'Start the game\'s preview server (reloads on every save) and return its address; open it in your own browser beside the chat. Called again, returns the running one.', inputSchema: { type: 'object', properties: { ...dirProp } } },
+    { name: 'image', description: 'Return a picture from the game folder (a target frame, the key art, a capture) so it shows in the chat.', inputSchema: { type: 'object', properties: { ...dirProp, path: { type: 'string' } }, required: ['path'] } },
+    { name: 'run', description: `Any other funtools command, by its words (["look","--hud"], ["playtest"], ["character","get","…"]). Never publish, login or logout: the person runs those.`, inputSchema: { type: 'object', properties: { ...dirProp, args: { type: 'array', items: { type: 'string' } } }, required: ['args'] } },
+];
+export function toolList() {
+    return [
+        ...TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: { type: 'object', properties: t.props, ...(t.required ? { required: t.required } : {}) } })),
+        ...EXTRA,
+    ];
+}
+function runCli(o, dir, args, timeoutMs = 300_000) {
+    return new Promise((done) => {
+        const child = spawn(o.bin[0], [...o.bin.slice(1), ...args], { cwd: dir, env: { ...process.env, ...o.env, FUNTOOLS_NO_UPDATE_CHECK: '1', NO_COLOR: '1', FORCE_COLOR: '0' }, stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        child.stdout.on('data', (b) => { out += b; });
+        child.stderr.on('data', (b) => { out += b; });
+        const t = setTimeout(() => { out += `\n(stopped after ${Math.round(timeoutMs / 1000)} s)`; child.kill('SIGTERM'); }, timeoutMs);
+        child.on('close', (code) => { clearTimeout(t); done({ code: code ?? 3, out: out.replace(/\x1b\[[0-9;]*m/g, '').trim() }); });
+        child.on('error', (e) => { clearTimeout(t); done({ code: 3, out: String(e.message) }); });
+    });
+}
+export function newPictures(dir, since) {
+    const found = [];
+    const walk = (d, depth) => {
+        let names = [];
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(d, n);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth < 3)
+                    walk(p, depth + 1);
+                continue;
+            }
+            if (MIME[extname(n).toLowerCase()] && st.mtimeMs >= since)
+                found.push({ p, t: st.mtimeMs });
+        }
+    };
+    for (const rel of PICTURE_DIRS)
+        walk(join(dir, rel), 0);
+    return found.sort((a, b) => b.t - a.t).map((f) => f.p);
+}
+function imageContent(file) {
+    const mime = MIME[extname(file).toLowerCase()];
+    if (!mime)
+        return null;
+    const st = statSync(file);
+    if (st.size > MAX_IMAGE_BYTES)
+        return null;
+    return { type: 'image', data: readFileSync(file).toString('base64'), mimeType: mime };
+}
+const EXIT_WORD = { 0: 'pass', 1: 'fail', 2: 'not observed', 3: 'error' };
+const list = (v) => (Array.isArray(v) ? v.map(String) : typeof v === 'string' ? [v] : []);
+export function localArgv(tool, a) {
+    const model = String(a.model);
+    const flag = (f, v) => (v === undefined || v === null || v === '' ? [] : [f, String(v)]);
+    const tags = list(a.tags).length ? ['--tags', list(a.tags).join(',')] : [];
+    if (tool === 'cast_voice') {
+        if (!str(a.name))
+            return 'cast_voice needs name';
+        return ['gen', 'voice', String(a.name), ...flag('--preset', a.preset), ...tags, ...flag('--description', a.description), ...flag('--sample', a.sample), '--model', model, '--json'];
+    }
+    if (tool === 'voice_line') {
+        if (!str(a.text))
+            return 'voice_line needs text';
+        const emotion = list(a.emotion).length ? ['--emotion', list(a.emotion).join(',')] : [];
+        return ['gen', 'line', String(a.text), ...flag('--preset', a.preset), ...tags, ...emotion, ...flag('--voice', a.voice_asset_id), '--model', model, '--json'];
+    }
+    if (tool === 'dialogue') {
+        if (!Array.isArray(a.lines) || !a.lines.length)
+            return 'dialogue needs lines';
+        const file = join(mkdtempSync(join(tmpdir(), 'funtools-scene-')), 'dialogue.json');
+        writeFileSync(file, JSON.stringify({ lines: a.lines, ...(a.cast !== undefined ? { cast: a.cast } : {}) }));
+        return ['gen', 'dialogue', file, ...flag('--gap', a.gap_ms), '--model', model, '--json'];
+    }
+    return `${model} runs on this machine for cast_voice, voice_line and dialogue, not ${tool}`;
+}
+export function createServer(o) {
+    const devs = new Map();
+    const log = o.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const hosted = o.hosted === undefined ? hostedFromApi(log, { onChange: () => o.notify?.({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' }) }) : o.hosted;
+    const local = new Set(toolList().map((t) => String(t.name)));
+    async function allTools() {
+        const theirs = hosted ? (await hosted.list()).filter((t) => !local.has(String(t.name))).map((t) => withModels(t)) : [];
+        return [...toolList(), ...theirs];
+    }
+    const gameDir = (a) => {
+        const d = str(a.dir) ? (isAbsolute(String(a.dir)) ? String(a.dir) : resolve(o.cwd, String(a.dir))) : o.cwd;
+        if (!existsSync(d))
+            throw new Error(`no folder ${d}`);
+        return d;
+    };
+    async function call(name, a) {
+        if (typeof a.model === 'string' && localIds(name).includes(a.model)) {
+            const argv = localArgv(name, a);
+            if (typeof argv === 'string')
+                return { content: [{ type: 'text', text: argv }], isError: true };
+            const r = await runCli(o, gameDir(a), argv, 900_000);
+            return { content: [{ type: 'text', text: `${r.out}\n\n(exit ${r.code}: ${EXIT_WORD[r.code] ?? 'error'})` }], ...(r.code !== 0 ? { isError: true } : {}) };
+        }
+        if (!local.has(name) && hosted && (await hosted.list()).some((t) => t.name === name)) {
+            return (await hosted.call(name, a));
+        }
+        if (name === 'image') {
+            const dir = gameDir(a);
+            const file = resolve(dir, String(a.path ?? ''));
+            if (relative(dir, file).startsWith('..') || !existsSync(file))
+                return { content: [{ type: 'text', text: `no picture at ${a.path} in the game folder` }], isError: true };
+            const img = imageContent(file);
+            return img ? { content: [img, { type: 'text', text: relative(dir, file) }] } : { content: [{ type: 'text', text: `${a.path}: not a picture under ${MAX_IMAGE_BYTES / 1e6} MB (png, jpg, webp)` }], isError: true };
+        }
+        if (name === 'dev')
+            return dev(gameDir(a));
+        let argv;
+        let timeoutMs;
+        if (name === 'run') {
+            const args = Array.isArray(a.args) ? a.args.map(String) : [];
+            if (!args.length || !RUN_ALLOWED.has(args[0]))
+                return { content: [{ type: 'text', text: `run takes a funtools command from the toolbox (${[...RUN_ALLOWED].slice(0, 12).join(', ')}, …); publish, login and logout are the person's to run` }], isError: true };
+            argv = args;
+            timeoutMs = 1_800_000;
+        }
+        else {
+            const t = TOOLS.find((x) => x.name === name);
+            if (!t)
+                return { content: [{ type: 'text', text: `no tool ${name}` }], isError: true };
+            for (const r of t.required ?? [])
+                if (a[r] === undefined || a[r] === '')
+                    return { content: [{ type: 'text', text: `${name} needs ${r}` }], isError: true };
+            argv = t.argv(a);
+            timeoutMs = t.timeoutMs;
+        }
+        if (name === 'flow_start') {
+            const target = str(a.dir) ? (isAbsolute(String(a.dir)) ? String(a.dir) : resolve(o.cwd, String(a.dir))) : o.cwd;
+            argv = argv.map((x, i) => (i === 2 && x === '.' ? target : x));
+            const r = await runCli(o, o.cwd, argv, timeoutMs);
+            return { content: [{ type: 'text', text: `${r.out}\n\n(exit ${r.code}: ${EXIT_WORD[r.code] ?? 'error'})` }], ...(r.code === 3 ? { isError: true } : {}) };
+        }
+        const dir = gameDir(a);
+        const since = Date.now() - 1000;
+        if (name === 'compose_video' && !existsSync(resolve(dir, composition(a)))) {
+            if (!str(a.starter))
+                return { content: [{ type: 'text', text: `no composition at ${composition(a)}: give starter (trailer, post or endcard) to write one first` }], isError: true };
+            const made = await runCli(o, dir, ['compose', 'new', String(a.starter), '.', ...opt('--aspect', a.aspect), ...opt('--seconds', a.seconds), ...(str(a.composition) ? ['--name', basename(String(a.composition)).replace(/\.html?$/i, '')] : [])], 120_000);
+            if (made.code !== 0)
+                return { content: [{ type: 'text', text: `${made.out}\n\n(exit ${made.code}: ${EXIT_WORD[made.code] ?? 'error'})` }], isError: true };
+        }
+        const says = name === 'run' ? `running ${argv[0]}` : ACTIVITY_WORDS[name] ?? 'working';
+        setActivity(dir, { tool: name, says, started_at: new Date().toISOString() });
+        let r;
+        try {
+            r = await runCli(o, dir, argv, timeoutMs);
+        }
+        finally {
+            setActivity(dir, null);
+        }
+        if (!name.startsWith('flow') && existsSync(join(dir, 'funpixel.json')))
+            await runCli(o, dir, ['flow', '--json'], 60_000);
+        const sheet = name === 'compose_video' ? join(dir, '.funtools', 'compose', `${basename(composition(a)).replace(/\.html?$/i, '')}.sheet.jpg`)
+            : name === 'ad_variations' ? join(dir, ADS_OUT, 'sheet.png') : null;
+        const pics = (sheet ? (existsSync(sheet) && statSync(sheet).mtimeMs >= since ? [sheet] : []) : newPictures(dir, since).slice(0, MAX_IMAGES)).map(imageContent).filter((x) => !!x);
+        return { content: [{ type: 'text', text: `${r.out}\n\n(exit ${r.code}: ${EXIT_WORD[r.code] ?? 'error'})` }, ...pics], ...(r.code === 3 ? { isError: true } : {}) };
+    }
+    function dev(dir) {
+        const running = devs.get(dir);
+        if (running && running.child.exitCode === null)
+            return Promise.resolve({ content: [{ type: 'text', text: `the preview is running at ${running.url}` }] });
+        return new Promise((done) => {
+            const child = spawn(o.bin[0], [...o.bin.slice(1), 'dev', '.'], { cwd: dir, env: { ...process.env, ...o.env, FUNTOOLS_NO_UPDATE_CHECK: '1', NO_COLOR: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+            let out = '';
+            const t = setTimeout(() => done({ content: [{ type: 'text', text: `the preview did not report an address within 90 s:\n${out.slice(-1500)}` }], isError: true }), 90_000);
+            const read = (b) => {
+                out += b.toString();
+                const m = /(https?:\/\/(?:localhost|127\.0\.0\.1):\d+\/?)/.exec(out.replace(/\x1b\[[0-9;]*m/g, ''));
+                if (m) {
+                    clearTimeout(t);
+                    devs.set(dir, { child, url: m[1] });
+                    done({ content: [{ type: 'text', text: `the preview is running at ${m[1]}; it reloads on every save. Open it beside the chat.` }] });
+                }
+            };
+            child.stdout.on('data', read);
+            child.stderr.on('data', read);
+            child.on('exit', () => { if (devs.get(dir)?.child === child)
+                devs.delete(dir); });
+        });
+    }
+    async function handle(msg) {
+        const id = msg.id;
+        const method = String(msg.method ?? '');
+        const reply = (result) => ({ jsonrpc: '2.0', id, result });
+        const fail = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+        if (id === undefined)
+            return null;
+        try {
+            if (method === 'initialize') {
+                const asked = msg.params?.protocolVersion;
+                return reply({ protocolVersion: typeof asked === 'string' ? asked : PROTOCOL, capabilities: { tools: { listChanged: true } }, serverInfo: { name: 'funtools', version: currentVersion() }, instructions: 'The Funpixel game kit. Call `flow` at the start of every turn: it names the one next step and the tool for it. Pass the game folder as `dir` (an absolute path) on every call: the server does not start in it. The hosted Funpixel tools are here too (generation of pictures, sound, music, video and 3D models, and the rest); they run on the account `funtools login` signed in, and a call that cannot run says why and what to run.' });
+            }
+            if (method === 'ping')
+                return reply({});
+            if (method === 'tools/list')
+                return reply({ tools: await allTools() });
+            if (method === 'tools/call') {
+                const p = (msg.params ?? {});
+                return reply(await call(String(p.name ?? ''), (p.arguments ?? {})));
+            }
+            return fail(-32601, `no method ${method}`);
+        }
+        catch (e) {
+            log(`funtools mcp: ${e.message}`);
+            return method === 'tools/call' ? reply({ content: [{ type: 'text', text: e.message }], isError: true }) : fail(-32603, e.message);
+        }
+    }
+    const stop = () => { for (const { child } of devs.values())
+        child.kill('SIGTERM'); devs.clear(); };
+    return { handle, stop };
+}
+export async function serveStdio(o) {
+    const s = createServer({ ...o, notify: (msg) => process.stdout.write(JSON.stringify(msg) + '\n') });
+    const rl = createInterface({ input: process.stdin });
+    const pending = [];
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'not JSON' } }) + '\n');
+            return;
+        }
+        pending.push(s.handle(msg).then((r) => { if (r)
+            process.stdout.write(JSON.stringify(r) + '\n'); }));
+    });
+    await new Promise((done) => rl.on('close', () => done()));
+    await Promise.allSettled(pending);
+    s.stop();
+}

package/dist/memory/decisions.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const DECISIONS_FILE = join('design', 'decisions.md');
+const HEAD = `# Decisions
+
+Each choice made against its alternative, and why, so a later session neither re-argues it nor
+reverses it without a record. Newest last. Replacing one is normal: a new entry says which it
+supersedes (\`npx @funpixel/tools decide "…" --because "…" --supersedes D3\`). Edit by hand freely;
+keep the \`## D<n> · <date> · <choice>\` heading shape.
+`;
+const HEADING = /^##\s+(D\d+)\b\s*[·|-]?\s*(\d{4}-\d{2}-\d{2})?\s*[·|-]?\s*(.*)$/;
+const FIELD = /^[-*]\s*\**(Over|Because|Supersedes|Superseded by|Owner|Shot|From|Touches|Status)\**:\**\s*(.*)$/i;
+const ids = (s) => [...s.matchAll(/\bD\d+\b/g)].map((m) => m[0]);
+export function parseDecisions(text) {
+    const out = [];
+    let cur = null;
+    for (const line of text.split(/\r?\n/)) {
+        const h = HEADING.exec(line.trim());
+        if (h) {
+            cur = { id: h[1], date: h[2] ?? '', choice: h[3].trim(), supersedes: [], touches: [] };
+            out.push(cur);
+            continue;
+        }
+        if (/^#{1,2}\s/.test(line)) {
+            cur = null;
+            continue;
+        }
+        const f = cur && FIELD.exec(line.trim());
+        if (!cur || !f)
+            continue;
+        const key = f[1].toLowerCase(), value = f[2].trim();
+        if (key === 'over')
+            cur.over = value;
+        else if (key === 'because')
+            cur.because = value;
+        else if (key === 'supersedes')
+            cur.supersedes.push(...ids(value));
+        else if (key === 'owner')
+            cur.owner = value.replace(/^"|"$/g, '');
+        else if (key === 'shot')
+            cur.shot = value;
+        else if (key === 'from')
+            cur.from = value;
+        else if (key === 'touches')
+            cur.touches.push(...value.split(',').map((x) => x.trim()).filter(Boolean));
+        else if (key === 'status')
+            cur.status = value;
+        else
+            cur.supersededBy = ids(value)[0] ?? cur.supersededBy;
+    }
+    for (const d of out)
+        for (const old of d.supersedes) {
+            const o = out.find((x) => x.id === old);
+            if (o && !o.supersededBy)
+                o.supersededBy = d.id;
+        }
+    return out;
+}
+export function readDecisions(root) {
+    const file = join(root, DECISIONS_FILE);
+    return existsSync(file) ? parseDecisions(readFileSync(file, 'utf8')) : [];
+}
+export const liveDecisions = (all) => all.filter((d) => !d.supersededBy);
+export function addDecision(root, d, now = new Date()) {
+    const file = join(root, DECISIONS_FILE);
+    let text = existsSync(file) ? readFileSync(file, 'utf8') : HEAD;
+    const all = parseDecisions(text);
+    const supersedes = [...new Set((d.supersedes ?? []).map((s) => s.toUpperCase().replace(/^(\d+)$/, 'D$1')))];
+    for (const old of supersedes) {
+        const o = all.find((x) => x.id === old);
+        if (!o)
+            throw new Error(`no decision ${old} in ${DECISIONS_FILE} (it holds ${all.map((x) => x.id).join(', ') || 'none'})`);
+        if (o.supersededBy)
+            throw new Error(`${old} was already replaced by ${o.supersededBy}; supersede ${o.supersededBy} instead`);
+    }
+    const id = `D${all.reduce((m, x) => Math.max(m, Number(x.id.slice(1))), 0) + 1}`;
+    const date = now.toISOString().slice(0, 10);
+    const one = (s) => s.replace(/\s+/g, ' ').trim();
+    if (supersedes.length) {
+        const lines = text.split('\n');
+        for (const old of supersedes) {
+            const start = lines.findIndex((l) => HEADING.exec(l.trim())?.[1] === old);
+            let end = start + 1;
+            while (end < lines.length && !/^#{1,2}\s/.test(lines[end]))
+                end++;
+            let at = end;
+            while (at > start + 1 && !lines[at - 1].trim())
+                at--;
+            lines.splice(at, 0, `- Superseded by: ${id} (${date})`);
+        }
+        text = lines.join('\n');
+    }
+    const entry = [
+        `## ${id} · ${date} · ${one(d.choice)}`,
+        ...(d.over ? [`- Over: ${one(d.over)}`] : []),
+        ...(d.owner ? [`- Owner: "${one(d.owner)}"`] : []),
+        ...(d.shot ? [`- Shot: ${one(d.shot)}`] : []),
+        ...(d.from ? [`- From: ${one(d.from)}`] : []),
+        `- Because: ${one(d.because)}`,
+        ...(d.touches?.length ? [`- Touches: ${d.touches.map(one).join(', ')}`] : []),
+        ...(d.status ? [`- Status: ${one(d.status)}`] : []),
+        ...(supersedes.length ? [`- Supersedes: ${supersedes.join(', ')}`] : []),
+    ].join('\n');
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${text.replace(/\s*$/, '')}\n\n${entry}\n`);
+    return { id, date, choice: one(d.choice), ...(d.over ? { over: one(d.over) } : {}), because: one(d.because), supersedes,
+        ...(d.owner ? { owner: one(d.owner) } : {}), ...(d.shot ? { shot: one(d.shot) } : {}), ...(d.from ? { from: one(d.from) } : {}),
+        touches: (d.touches ?? []).map(one), ...(d.status ? { status: one(d.status) } : {}) };
+}
+export function setDecisionStatus(root, id, status) {
+    const file = join(root, DECISIONS_FILE);
+    if (!existsSync(file))
+        return false;
+    const lines = readFileSync(file, 'utf8').split('\n');
+    const start = lines.findIndex((l) => HEADING.exec(l.trim())?.[1] === id);
+    if (start < 0)
+        return false;
+    let end = start + 1;
+    while (end < lines.length && !/^#{1,2}\s/.test(lines[end]))
+        end++;
+    const at = lines.slice(start + 1, end).findIndex((l) => /^[-*]\s*\**Status\**:/i.test(l.trim()));
+    const line = `- Status: ${status.replace(/\s+/g, ' ').trim()}`;
+    if (at >= 0)
+        lines[start + 1 + at] = line;
+    else {
+        let k = end;
+        while (k > start + 1 && !lines[k - 1].trim())
+            k--;
+        lines.splice(k, 0, line);
+    }
+    writeFileSync(file, lines.join('\n'));
+    return true;
+}
+export const isOpenDecision = (d) => !d.supersededBy && /^open\b/i.test(d.status ?? '');
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+export function decisionLine(d) {
+    return `- ${d.id} ${clip(d.choice, 100)}${d.over ? `, over ${clip(d.over, 60)}` : ''}${d.because ? ` — ${clip(d.because, 100)}` : ''}${d.supersedes.length ? ` (replaces ${d.supersedes.join(', ')})` : ''}${d.status && /^open\b/i.test(d.status) ? ' [open: not built yet]' : ''}`;
+}

package/dist/memory/journal.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stagedDigests } from "../verify/fingerprint.js";
+export const JOURNAL_FILE = join('.funtools', 'journal.jsonl');
+export const AGENT_FILES = join('.funtools', 'agent-files.json');
+export function readJournal(root) {
+    const file = join(root, JOURNAL_FILE);
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e.what === 'string' && typeof e.at === 'string')
+                out.push(e);
+        }
+        catch { }
+    }
+    return out;
+}
+export function appendJournal(root, entry, now = new Date()) {
+    const full = { at: now.toISOString().replace(/\.\d+Z$/, 'Z'), ...entry };
+    mkdirSync(join(root, '.funtools'), { recursive: true });
+    appendFileSync(join(root, JOURNAL_FILE), JSON.stringify(full) + '\n');
+    return full;
+}
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+const when = (at) => at.replace('T', ' ').slice(0, 16);
+const fileList = (files, n = 4) => files.slice(0, n).join(', ') + (files.length > n ? ` and ${files.length - n} more` : '');
+export function journalLine(e) {
+    if (e.inferred) {
+        return `- ${when(e.at)} · detected, not told: ${e.what}${e.files?.length ? ` (${fileList(e.files)})` : ''}; who and why unknown`;
+    }
+    const values = e.values ? Object.entries(e.values).map(([k, v]) => `${k}=${v}`).join(', ') : '';
+    const touched = [values, e.files?.length ? fileList(e.files) : ''].filter(Boolean).join(' · ');
+    return `- ${when(e.at)} · ${e.by}${e.via === 'agent' ? ' (via the agent)' : ''}: ${clip(e.what, 120)}${e.why ? ` — because ${clip(e.why, 120)}` : ''}${touched ? ` · ${touched}` : ''}`;
+}
+export function explained(entries) {
+    const bare = (f) => f.replace(/ \((new|removed)\)$/, '');
+    return entries.filter((e, i) => !e.inferred || !e.files?.length
+        || !entries.slice(i + 1).some((t) => !t.inferred && t.files?.length && e.files.every((f) => t.files.includes(bare(f)))));
+}
+export async function trackedHashes(root, digests) {
+    const out = {};
+    for (const e of digests ?? await stagedDigests(root))
+        out[e.path] = e.digest.slice(0, 16);
+    const design = join(root, 'design');
+    if (existsSync(design)) {
+        for (const f of readdirSync(design))
+            if (f.endsWith('.md'))
+                out[`design/${f}`] = hash(readFileSync(join(design, f)));
+    }
+    return out;
+}
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+export function readAgentFiles(root) {
+    try {
+        const s = JSON.parse(readFileSync(join(root, AGENT_FILES), 'utf8'));
+        return s && typeof s.files === 'object' ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeAgentFiles(root, files, now = new Date()) {
+    mkdirSync(join(root, '.funtools'), { recursive: true });
+    writeFileSync(join(root, AGENT_FILES), JSON.stringify({ at: now.toISOString(), files }) + '\n');
+}
+export function recordAgentFile(root, rel, now = new Date()) {
+    const snap = readAgentFiles(root);
+    if (!snap)
+        return;
+    const path = join(root, rel);
+    if (/^(\.funtools|node_modules|dist|\.git)\//.test(rel) || rel.startsWith('..'))
+        return;
+    const files = { ...snap.files };
+    if (existsSync(path))
+        files[rel] = hash(readFileSync(path));
+    else
+        delete files[rel];
+    writeAgentFiles(root, files, now);
+}
+export function changedFiles(before, now, exists = () => false) {
+    const out = [];
+    for (const [p, h] of Object.entries(now))
+        if (before[p] !== h)
+            out.push(before[p] ? p : `${p} (new)`);
+    for (const p of Object.keys(before))
+        if (!(p in now) && !exists(p))
+            out.push(`${p} (removed)`);
+    return out.sort();
+}
+export async function noticeOutsideChanges(root, now = new Date(), digests) {
+    const snap = readAgentFiles(root);
+    if (!snap)
+        return null;
+    const current = await trackedHashes(root, digests);
+    const changed = changedFiles(snap.files, current, (p) => existsSync(join(root, p)));
+    if (!changed.length)
+        return null;
+    const entry = appendJournal(root, {
+        by: 'unknown', via: 'detected', inferred: true,
+        what: `${changed.length} file(s) changed while no agent turn was running`, files: changed,
+    }, now);
+    writeAgentFiles(root, current, now);
+    return entry;
+}