backdraw 0.0.0-stage → 2.1.0

package/lib/extension-calls.js

@@ -0,0 +1,59 @@
+'use strict';
+// The extension's own requests to the host: {type:'call', reqId, method, params}, answered with
+// {type:'reply', reqId, ok, result | error, code}. Only EXTENSION_METHODS are reachable this way
+// (never generate, diagnose or set_config). Image data comes first in {type:'call_chunk', reqId,
+// seq, total, data} pieces, like ref_chunk the other way. Pure: the host passes its handlers.
+const { EXTENSION_METHODS } = require('./collections');
+
+const MAX_REPLY = 1000000; // bytes; Chrome drops host->extension messages over 1 MB
+const callError = (message, code) => Object.assign(new Error(message), { code });
+
+// Collects call_chunk pieces per reqId. Pieces over maxChars in total, or with a bad seq, spoil the
+// call (it is answered with an error); calls whose "call" never comes are dropped after ttlMs. At
+// most maxPending calls collect data at a time; a call beyond that is spoiled from its first piece.
+function callAssembler(maxChars, ttlMs = 120000, now = Date.now, maxPending = 4) {
+  const calls = new Map(); // reqId -> { parts, total, size, at, bad }
+  return {
+    chunk(msg) {
+      for (const [id, c] of calls) if (now() - c.at > ttlMs) calls.delete(id);
+      const busy = !calls.has(msg.reqId) && [...calls.values()].filter(c => !c.bad).length >= maxPending;
+      const c = calls.get(msg.reqId) || { parts: [], total: Number(msg.total) || 0, size: 0, at: now(), bad: false };
+      const data = typeof msg.data === 'string' ? msg.data : '';
+      c.size += data.length;
+      if (busy || c.size > maxChars || !Number.isInteger(msg.seq) || msg.seq < 0 || msg.seq >= c.total) Object.assign(c, { bad: true, parts: [] });
+      if (!c.bad) c.parts[msg.seq] = data;
+      calls.set(msg.reqId, c);
+    },
+    // The pieces of one call (null when it had none); they are forgotten either way.
+    take(reqId) {
+      const c = calls.get(reqId) || null;
+      calls.delete(reqId);
+      return c;
+    },
+    get pending() { return calls.size; },
+  };
+}
+
+async function answerCall(msg, handlers, pieces, maxMb) {
+  let reply;
+  try {
+    if (!EXTENSION_METHODS.has(msg.method) || typeof handlers[msg.method] !== 'function') {
+      throw callError(`The extension may not call "${msg.method}".`, 'NOT_ALLOWED');
+    }
+    const params = msg.params && typeof msg.params === 'object' && !Array.isArray(msg.params) ? { ...msg.params } : {};
+    if (pieces) {
+      if (pieces.bad) throw callError(`The image is larger than ${maxMb} MB or its pieces were malformed.`, 'TOO_LARGE');
+      for (let i = 0; i < pieces.total; i++) if (typeof pieces.parts[i] !== 'string') throw callError('The image did not arrive completely; please try again.', 'TRANSFER');
+      params.data = pieces.parts.join('');
+    }
+    reply = { type: 'reply', reqId: msg.reqId, ok: true, result: await handlers[msg.method](params) };
+  } catch (e) {
+    reply = { type: 'reply', reqId: msg.reqId, ok: false, error: e.message, code: e.code || 'ERROR' };
+  }
+  if (Buffer.byteLength(JSON.stringify(reply)) > MAX_REPLY) {
+    reply = { type: 'reply', reqId: msg.reqId, ok: false, error: 'The answer is too large for Chrome (over 1 MB).', code: 'TOO_LARGE' };
+  }
+  return reply;
+}
+
+module.exports = { MAX_REPLY, callAssembler, answerCall };

package/lib/gallery.js

@@ -0,0 +1,63 @@
+'use strict';
+// The gallery of the extension's side panel: the images of succeeded jobs. The panel names an image by
+// its job id and number (1-based, like the preview files) only; every path comes from the host's own
+// job records, never from the extension.
+const fs = require('fs');
+const path = require('path');
+const { cut, chars, isInside } = require('./collections');
+
+const PAGE_MAX = 100;
+const MAX_PROMPT = 300;
+// A preview goes to the extension in one native message, which Chrome caps at 1 MB (base64 adds a third).
+const MAX_PREVIEW_BYTES = 640 * 1024;
+
+const succeeded = j => !!j && j.status === 'succeeded' && Array.isArray(j.images);
+// A hand-edited jobs.json may hold anything: only absolute paths count as images.
+const usable = im => !!im && typeof im.path === 'string' && path.isAbsolute(im.path);
+const shortPrompt = s => (chars(s || '').length > MAX_PROMPT ? `${cut(s, MAX_PROMPT)}…` : String(s || ''));
+
+function fileExists(file) {
+  try { return fs.statSync(file).isFile(); } catch { return false; }
+}
+
+// Newest job first, a job's own images in their order. exists(path), when given, marks the files that
+// are gone (moved or deleted by hand); only the page asked for is checked.
+function listGallery(jobs, offset = 0, limit = 12, exists = null) {
+  const all = [];
+  for (const j of (Array.isArray(jobs) ? jobs : []).slice().reverse()) {
+    if (succeeded(j)) j.images.forEach((im, i) => { if (usable(im)) all.push({ j, im, n: i + 1 }); });
+  }
+  const from = Math.max(0, Math.floor(Number(offset)) || 0);
+  const size = Math.min(PAGE_MAX, Math.max(1, Math.floor(Number(limit)) || 12));
+  const items = all.slice(from, from + size).map(({ j, im, n }) => ({
+    jobId: j.id, n, createdAt: j.createdAt || null, prompt: shortPrompt(j.prompt), conversationUrl: j.conversationUrl || null,
+    path: im.path, width: im.width || null, height: im.height || null, aspect: im.aspect || null, preview: !!im.preview,
+    ...(exists ? { missing: !exists(im.path) } : {}),
+  }));
+  const end = from + items.length;
+  return { total: all.length, items, next: end < all.length ? end : null };
+}
+
+// { job, image } or null. n must be a whole number: "1" or 1.5 never match.
+function findJobImage(jobs, jobId, n) {
+  if (typeof jobId !== 'string' || !Number.isInteger(n) || n < 1) return null;
+  const job = (Array.isArray(jobs) ? jobs : []).find(j => j && j.id === jobId);
+  if (!succeeded(job)) return null;
+  const image = job.images[n - 1];
+  return usable(image) ? { job, image } : null;
+}
+
+// The preview JPEG the host saved for an image while it is still there (the host deletes previews
+// after 7 days): { data: base64 | null, mime }. Only files inside the previews folder are read.
+function readPreview(previewDir, image) {
+  const file = image && image.preview;
+  try {
+    if (typeof file === 'string' && isInside(previewDir, file) && fs.statSync(file).size <= MAX_PREVIEW_BYTES) {
+      const buf = fs.readFileSync(file);
+      if (buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return { data: buf.toString('base64'), mime: 'image/jpeg' };
+    }
+  } catch {}
+  return { data: null, mime: null };
+}
+
+module.exports = { PAGE_MAX, MAX_PROMPT, MAX_PREVIEW_BYTES, fileExists, listGallery, findJobImage, readPreview };

package/lib/limits.js

@@ -0,0 +1,18 @@
+'use strict';
+// Limits shared by the host, the MCP server, the CLI and (copied by hand) the extension.
+
+// Reference images attached to one ChatGPT message, counting reference_images and collection images
+// together. Tested on 21 Oct 2026: ChatGPT accepted 16 attachments in one message and its image used
+// all 16 (16 numbered colour squares came back as 16 blocks in order). ChatGPT allows up to 20 files
+// per message; 16 is also the most input images OpenAI's image edit API documents.
+const MAX_REFS = 16;
+// Largest single reference image.
+const MAX_REF_BYTES = 20 * 1024 * 1024;
+// All references of one message together: the extension hands them to the page in one call, and 16
+// large photos would pass Chrome's message limits. No more than the old limit allowed (4 x 20 MB).
+const MAX_REFS_TOTAL_BYTES = 80 * 1024 * 1024;
+// Largest image a reference collection keeps (extension/collections.js repeats it). Larger than
+// MAX_REF_BYTES: such an image stays in the collection but is left out of jobs.
+const MAX_COLLECTION_BYTES = 25 * 1024 * 1024;
+
+module.exports = { MAX_REFS, MAX_REF_BYTES, MAX_REFS_TOTAL_BYTES, MAX_COLLECTION_BYTES };

package/lib/mcp-clients.js

@@ -0,0 +1,178 @@
+'use strict';
+// The MCP clients `backdraw setup` can add Backdraw to by editing their config file, in the formats
+// of their official docs (the same as the README's manual setup). Claude Code and the Claude desktop
+// app are handled in install.js. Every change to an existing file is preceded by a timestamped .bak
+// copy; only the "backdraw" entry is added, updated or removed, everything else stays as it was.
+// env: { home, appData, which(cmd) -> path or null }
+const fs = require('fs');
+const path = require('path');
+const toml = require('./toml');
+
+const NAME = 'backdraw';
+
+const exists = p => { try { return fs.existsSync(p); } catch { return false; } };
+
+const FILE_CLIENTS = [
+  {
+    id: 'codex', label: 'Codex', format: 'toml',
+    file: env => path.join(env.home, '.codex', 'config.toml'),
+    detect: env => exists(path.join(env.home, '.codex')) || !!env.which('codex'),
+    entry: (node, server) => ({ command: node, args: [server] }),
+  },
+  {
+    id: 'cursor', label: 'Cursor', format: 'json', key: 'mcpServers',
+    file: env => path.join(env.home, '.cursor', 'mcp.json'),
+    detect: env => exists(path.join(env.home, '.cursor')),
+    entry: (node, server) => ({ type: 'stdio', command: node, args: [server] }),
+  },
+  {
+    id: 'vscode', label: 'VS Code', format: 'json', key: 'servers',
+    file: env => path.join(env.appData, 'Code', 'User', 'mcp.json'),
+    detect: env => exists(path.join(env.appData, 'Code', 'User')),
+    entry: (node, server) => ({ type: 'stdio', command: node, args: [server] }),
+  },
+  {
+    id: 'gemini', label: 'Gemini CLI', format: 'json', key: 'mcpServers',
+    file: env => path.join(env.home, '.gemini', 'settings.json'),
+    detect: env => exists(path.join(env.home, '.gemini')) || !!env.which('gemini'),
+    entry: (node, server) => ({ command: node, args: [server] }),
+  },
+];
+
+const byId = id => FILE_CLIENTS.find(c => c.id === id);
+
+function backupFile(file, now = new Date()) {
+  const backup = `${file}.${now.toISOString().replace(/[:.]/g, '-')}.bak`;
+  fs.copyFileSync(file, backup);
+  return backup;
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// JSON with comments and trailing commas (VS Code's and Gemini CLI's files allow both) as plain JSON.
+// Both are only looked for outside strings.
+function stripJsonc(text) {
+  const pass = (src, onChar) => {
+    let out = '';
+    for (let i = 0; i < src.length; i++) {
+      if (src[i] === '"') {
+        let j = i + 1;
+        while (j < src.length && src[j] !== '"') j += src[j] === '\\' ? 2 : 1;
+        out += src.slice(i, j + 1);
+        i = j;
+      } else {
+        const r = onChar(src, i);
+        out += r.text;
+        i = r.next;
+      }
+    }
+    return out;
+  };
+  const noComments = pass(text, (s, i) => {
+    if (s[i] === '/' && s[i + 1] === '/') {
+      let j = i;
+      while (j < s.length && s[j] !== '\n') j++;
+      return { text: '\n', next: j };
+    }
+    if (s[i] === '/' && s[i + 1] === '*') {
+      const end = s.indexOf('*/', i + 2);
+      return { text: '', next: end < 0 ? s.length : end + 1 };
+    }
+    return { text: s[i], next: i };
+  });
+  return pass(noComments, (s, i) => ({ text: s[i] === ',' && /^\s*[}\]]/.test(s.slice(i + 1)) ? '' : s[i], next: i }));
+}
+
+// The parsed JSON config ({} for a missing or empty file). Throws, without touching the file, when it
+// isn't a JSON object. Comments are read (tolerant: doctor and uninstall's listing), but a file with
+// comments is never rewritten (strict: add/remove), since Backdraw would drop them.
+function readJsonConfig(file, { tolerant = false } = {}) {
+  if (!exists(file)) return {};
+  const text = fs.readFileSync(file, 'utf8').replace(/^/, '');
+  if (!text.trim()) return {};
+  let json;
+  try { json = JSON.parse(text); } catch {
+    let commented = false;
+    try { json = JSON.parse(stripJsonc(text)); commented = true; } catch {}
+    if (!commented) throw new Error(`${file} is not valid JSON, so it was left alone; fix it or add Backdraw by hand (see the README)`);
+    if (!tolerant) throw new Error(`${file} has comments, so it was left alone (Backdraw would remove them); add Backdraw by hand (see the README)`);
+  }
+  if (!json || typeof json !== 'object' || Array.isArray(json)) throw new Error(`${file} does not hold a JSON object, so it was left alone`);
+  return json;
+}
+
+function servers(json, key, file) {
+  const s = json[key];
+  if (s === undefined) return {};
+  if (!s || typeof s !== 'object' || Array.isArray(s)) throw new Error(`"${key}" in ${file} is not an object, so the file was left alone`);
+  return s;
+}
+
+function writeText(file, text, existed, now) {
+  const backup = existed ? backupFile(file, now) : null;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return backup;
+}
+
+// The Backdraw entry a client's config has now: { file, entry } (entry null without one). Throws on a
+// file it can't read.
+function readEntry(client, env) {
+  const file = client.file(env);
+  if (client.format === 'toml') {
+    return { file, entry: exists(file) ? toml.readTable(fs.readFileSync(file, 'utf8'), ['mcp_servers', NAME]) : null };
+  }
+  return { file, entry: servers(readJsonConfig(file, { tolerant: true }), client.key, file)[NAME] || null };
+}
+
+// Adds or updates the entry. Returns { status: 'added' | 'updated' | 'unchanged', file, backup }.
+function addEntry(client, env, node, server, now = new Date()) {
+  const file = client.file(env);
+  const existed = exists(file);
+  const entry = client.entry(node, server);
+  if (client.format === 'toml') {
+    const before = existed ? fs.readFileSync(file, 'utf8') : '';
+    const had = toml.readTable(before, ['mcp_servers', NAME]);
+    const after = toml.setTable(before, ['mcp_servers', NAME], entry);
+    if (after === before) return { status: 'unchanged', file, backup: null };
+    return { status: had ? 'updated' : 'added', file, backup: writeText(file, after, existed, now) };
+  }
+  const json = readJsonConfig(file);
+  const list = servers(json, client.key, file);
+  const old = list[NAME];
+  const next = { ...(old && typeof old === 'object' ? old : {}), ...entry };
+  if (old && sameJson(old, next)) return { status: 'unchanged', file, backup: null };
+  json[client.key] = { ...list, [NAME]: next };
+  return { status: old ? 'updated' : 'added', file, backup: writeText(file, `${JSON.stringify(json, null, 2)}\n`, existed, now) };
+}
+
+// Removes the entry. Returns { status: 'removed' | 'absent', file, backup }.
+function removeEntry(client, env, now = new Date()) {
+  const file = client.file(env);
+  if (!exists(file)) return { status: 'absent', file, backup: null };
+  if (client.format === 'toml') {
+    const before = fs.readFileSync(file, 'utf8');
+    if (!toml.readTable(before, ['mcp_servers', NAME])) return { status: 'absent', file, backup: null };
+    return { status: 'removed', file, backup: writeText(file, toml.removeTable(before, ['mcp_servers', NAME]), true, now) };
+  }
+  const json = readJsonConfig(file);
+  const list = servers(json, client.key, file);
+  if (!(NAME in list)) return { status: 'absent', file, backup: null };
+  const { [NAME]: _gone, ...rest } = list;
+  json[client.key] = rest;
+  return { status: 'removed', file, backup: writeText(file, `${JSON.stringify(json, null, 2)}\n`, true, now) };
+}
+
+// Whether an entry starts this install's server: the right script, and a command that exists
+// ("node" on PATH counts). Returns null when it does, or what is wrong.
+function entryProblem(entry, server, commandExists) {
+  if (!entry) return 'no Backdraw entry';
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  if (!args.some(a => typeof a === 'string' && path.resolve(a).toLowerCase() === path.resolve(server).toLowerCase())) {
+    return `points to ${args.find(a => /mcp-server\.js$/i.test(String(a))) || 'another script'}, not ${server}`;
+  }
+  if (typeof entry.command !== 'string' || !commandExists(entry.command)) return `its command ${entry.command || '(none)'} was not found`;
+  return null;
+}
+
+module.exports = { NAME, FILE_CLIENTS, byId, backupFile, stripJsonc, readJsonConfig, readEntry, addEntry, removeEntry, entryProblem };

package/lib/naming.js

@@ -0,0 +1,25 @@
+'use strict';
+// File names for saved images: a local timestamp plus a short ASCII slug of the prompt, and the
+// extension read from the image bytes themselves.
+
+function stamp(d = new Date()) {
+  const p = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+function slugify(s) {
+  const tr = { ç: 'c', ğ: 'g', ı: 'i', ö: 'o', ş: 's', ü: 'u', Ç: 'c', Ğ: 'g', İ: 'i', Ö: 'o', Ş: 's', Ü: 'u' };
+  const slug = s.replace(/[çğıöşüÇĞİÖŞÜ]/g, c => tr[c]).normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 48).replace(/-+$/, '');
+  return slug || 'image';
+}
+
+function sniffExt(b) {
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e) return 'png';
+  if (b[0] === 0xff && b[1] === 0xd8) return 'jpg';
+  if (b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP') return 'webp';
+  if (b.subarray(0, 3).toString('latin1') === 'GIF') return 'gif';
+  return null;
+}
+
+module.exports = { stamp, slugify, sniffExt };

package/lib/png.js

@@ -0,0 +1,24 @@
+'use strict';
+// PNG header facts (pure): whether ChatGPT's file can hold transparency at all. The pixels
+// themselves are measured by the extension; this only reads IHDR and looks for a tRNS chunk.
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// null unless buf starts with a complete PNG signature and IHDR. Color types 4 (gray+alpha) and 6
+// (RGBA) have an alpha channel; tRNS gives the others transparent colors. tRNS must come before
+// the first IDAT, so the scan stops there (or at a truncated chunk).
+function pngInfo(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 29 ||!buf.subarray(0, 8).equals(SIGNATURE)) return null;
+  if (buf.readUInt32BE(8) < 13 || buf.toString('latin1', 12, 16) !== 'IHDR') return null;
+  const colorType = buf[25];
+  let trns = false;
+  for (let pos = 8; pos + 8 <= buf.length;) {
+    const type = buf.toString('latin1', pos + 4, pos + 8);
+    if (type === 'tRNS') { trns = true; break; }
+    if (type === 'IDAT' || type === 'IEND') break;
+    pos += 12 + buf.readUInt32BE(pos);
+  }
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), bitDepth: buf[24], colorType, alphaChannel: colorType === 4 || colorType === 6, trns };
+}
+
+module.exports = { pngInfo };

package/lib/projects.js

@@ -0,0 +1,56 @@
+'use strict';
+// Matching ChatGPT projects by name or link (pure; the host asks the extension for the list).
+
+function normName(s) {
+  return String(s || '').toLocaleLowerCase('tr').replace(/ı/g, 'i').normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '');
+}
+
+function similarity(a, b) {
+  if (!a || !b) return 0;
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return 1 - row[b.length] / Math.max(a.length, b.length);
+}
+
+function parseProjectUrl(url) {
+  let u;
+  try { u = new URL(String(url)); } catch { return null; }
+  if (!/^(www\.)?chatgpt\.com$/i.test(u.hostname)) return null;
+  const m = u.pathname.match(/^\/g\/(g-p-[0-9a-f]+)(-[^/]*)?(?:\/|$)/i);
+  if (!m) return null;
+  return { id: m[1], url: `https://chatgpt.com/g/${m[1]}${m[2] || ''}/project`, slug: (m[2] || '').slice(1) };
+}
+
+// Scores every project against the wanted name: 2 for the same normalized name, 1.5 when one
+// contains the other, otherwise the edit-distance similarity (0-1). Best first; ties share the
+// best score.
+function rankProjects(projects, wantedName) {
+  const wanted = normName(wantedName);
+  const scored = projects.map(x => {
+    const n = normName(x.name);
+    const score = n === wanted ? 2 : n && (n.includes(wanted) || wanted.includes(n)) ? 1.5 : similarity(n, wanted);
+    return { ...x, score };
+  }).sort((a, b) => b.score - a.score);
+  const best = scored[0] || null;
+  return { best, ties: best ? scored.filter(x => x.score === best.score) : [], scored };
+}
+
+// The project a name selects: the best match, if it scores at least 0.7 and no other project
+// scores the same. Otherwise error is NOT_FOUND, or AMBIGUOUS with the tied projects.
+function pickProject(projects, wantedName) {
+  const { best, ties } = rankProjects(projects, wantedName);
+  if (!best || best.score < 0.7) return { error: 'NOT_FOUND' };
+  if (ties.length > 1) return { error: 'AMBIGUOUS', ties };
+  return { project: best };
+}
+
+module.exports = { normName, similarity, parseProjectUrl, rankProjects, pickProject };

package/lib/prompt.js

@@ -0,0 +1,25 @@
+'use strict';
+// The message the host sends to ChatGPT for a job.
+const { promptLines } = require('./aspect');
+
+// The wording nudges ChatGPT to call its image tool instead of asking questions first.
+function withLead(job) {
+  if (job.references && job.references.length) {
+    const what = job.references.length > 1 ? 'The attached images are references' : 'The attached image is the reference';
+    return `${what}. Follow the instructions below; when they ask for an edit, change only what is asked and keep everything else identical. Don't ask follow-up questions; generate the image directly.\n\n${job.prompt}`;
+  }
+  if (job.startUrl && /\/c\/[0-9a-f-]{8,}/i.test(job.startUrl)) {
+    return `Update the image with the changes below and generate the new image directly, without follow-up questions.\n\n${job.prompt}`;
+  }
+  return `Generate an image from the description below. Don't ask follow-up questions; create the image directly.\n\n${job.prompt}`;
+}
+
+// Shape and background requests go after the prompt, so its opening (which the extension uses to
+// recognise the sent message) stays the same.
+function buildText(job) {
+  if (job.sendAsIs) return job.prompt;
+  const extra = promptLines(job.aspect || null, !!job.transparent);
+  return extra.length ? `${withLead(job)}\n\n${extra.join('\n')}` : withLead(job);
+}
+
+module.exports = { buildText };

package/lib/protocol.js

@@ -0,0 +1,50 @@
+'use strict';
+// MCP protocol revisions. Legacy clients open with an initialize handshake; modern clients
+// (2026-07-28) send no handshake and name the version in params._meta of every request instead.
+// The server speaks both: a request carrying the _meta version is served statelessly, an
+// initialize request selects legacy semantics.
+
+const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const MODERN_VERSIONS = ['2026-07-28'];
+const SUPPORTED_VERSIONS = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+const VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+const SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
+const UNSUPPORTED_VERSION = -32022;
+// The tool list never changes while the server runs, and it is the same for every user.
+const CACHED = new Set(['server/discover', 'tools/list', 'prompts/list', 'resources/list']);
+const CACHE = { ttlMs: 3600000, cacheScope: 'public' };
+
+// Echo a legacy version we know; answer anything else with our newest one and let the client
+// decide whether it can continue (the legacy rule).
+function negotiateLegacy(requested) {
+  return LEGACY_VERSIONS.includes(requested) ? requested : LEGACY_VERSIONS[0];
+}
+
+// The version a modern request names, or null for a legacy request (no _meta version).
+function requestVersion(params) {
+  const v = params && params._meta && params._meta[VERSION_KEY];
+  return v === undefined || v === null ? null : String(v);
+}
+
+function unsupportedVersion(requested) {
+  return { code: UNSUPPORTED_VERSION, message: 'Unsupported protocol version', data: { supported: [...SUPPORTED_VERSIONS], requested } };
+}
+
+// Every modern result says it is complete and who answered; cacheable results also say for how long.
+function modernResult(method, result, serverInfo) {
+  return {
+    ...result,
+    ...(CACHED.has(method) ? CACHE : {}),
+    resultType: 'complete',
+    _meta: { ...(result && result._meta), [SERVER_INFO_KEY]: serverInfo },
+  };
+}
+
+function discoverResult(serverInfo, instructions) {
+  return modernResult('server/discover', { supportedVersions: [...SUPPORTED_VERSIONS], capabilities: { tools: {} }, instructions }, serverInfo);
+}
+
+module.exports = {
+  LEGACY_VERSIONS, MODERN_VERSIONS, SUPPORTED_VERSIONS, VERSION_KEY, SERVER_INFO_KEY, UNSUPPORTED_VERSION,
+  negotiateLegacy, requestVersion, unsupportedVersion, modernResult, discoverResult,
+};