@mmerterden/multi-agent-toolkit-mcp 3.9.0 → 3.12.0

package/tools/code-intel/pool.js

@@ -0,0 +1,273 @@
+/**
+ * pool.js  -  one language server per workspace, kept warm, evicted politely.
+ *
+ * WHY POOL AT ALL. Measured against sourcekit-lsp 6.3.1 on a two-file package:
+ * `initialize` answers in ~600ms, but the background index that `references`
+ * and `workspace/symbol` depend on does not finish until ~5.8s. On a real
+ * package with dependencies the same sequence had not finished at 70s. Spawning
+ * per request pays that every time and throws the result away; the second
+ * question about the same repository should be fast, and it is only fast if the
+ * first one left something behind.
+ *
+ * WHY ONLY TWO. sourcekit-lsp with background indexing is a large resident
+ * process, and an MCP server quietly holding four of them is a bug report. Two
+ * covers the real pattern (one repo, sometimes a second) and the third eviction
+ * is the least recently used.
+ *
+ * WHY SERIALIZE PER ROOT. Every request about a file has to be preceded by that
+ * file being open on the server, and two tools interleaving didOpen/request on
+ * one server produce answers about the wrong document. Requests to DIFFERENT
+ * roots still run concurrently; only same-root work queues, and it queues behind
+ * something that is usually already warm.
+ *
+ * @module tools/code-intel/pool
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { createLspClient } from "./lsp-client.js";
+
+const IDLE_MS = 10 * 60 * 1000;
+const MAX_SERVERS = 2;
+const SWEEP_MS = 60 * 1000;
+/** Three crashes this close together is a loop, not bad luck. */
+const CRASH_WINDOW_MS = 60 * 1000;
+const CRASH_LIMIT = 3;
+const POISON_MS = 5 * 60 * 1000;
+
+const servers = new Map();
+/**
+ * One promise chain per key, held OUTSIDE the entry.
+ *
+ * It used to live on the entry as `entry.lock`, which meant a key with no entry
+ * yet had no lock at all: two concurrent calls for a cold root both walked
+ * straight past the barrier, both spawned a language server, and the second
+ * `servers.set` orphaned the first - never disposed, never swept, because the
+ * sweeper only walks this map. A leak of exactly the resident process this file
+ * caps at two.
+ */
+const locks = new Map();
+/** Crash records survive their entry, so a poison window is not lost on evict. */
+const crashHistory = new Map();
+let sweeper = null;
+
+function startSweeper() {
+  if (sweeper) return;
+  sweeper = setInterval(() => {
+    const now = Date.now();
+    for (const [key, e] of [...servers]) {
+      if (now - e.lastUsed > IDLE_MS) evict(key, "idle");
+    }
+    if (servers.size === 0) {
+      clearInterval(sweeper);
+      sweeper = null;
+    }
+  }, SWEEP_MS);
+  sweeper.unref?.();
+}
+
+function evict(key, why) {
+  const e = servers.get(key);
+  if (!e) return;
+  servers.delete(key);
+  e.evictedBecause = why;
+  try {
+    e.client.dispose();
+  } catch {
+    /* disposing a dead server is not an error */
+  }
+}
+
+/** Every server, gone. Wired into the host's own shutdown. */
+export function shutdownAllLsp() {
+  for (const key of [...servers.keys()]) evict(key, "shutdown");
+  locks.clear();
+  crashHistory.clear();
+  if (sweeper) {
+    clearInterval(sweeper);
+    sweeper = null;
+  }
+}
+
+/**
+ * Roots with work queued or in flight right now.
+ *
+ * Exported because the queue is the one piece of pool state nothing else can
+ * see: `poolStats()` lists servers, and a key can hold a queue without ever
+ * having started one - a start that failed, or a call still waiting its turn.
+ * A number here that only ever grows is the leak this returns to zero.
+ */
+export function queuedKeys() {
+  return [...locks.keys()];
+}
+
+export function poolStats() {
+  return [...servers.entries()].map(([key, e]) => ({
+    key,
+    pid: e.client.pid,
+    alive: e.client.alive,
+    openDocs: e.openDocs.size,
+    idleSec: Math.round((Date.now() - e.lastUsed) / 1000),
+  }));
+}
+
+/**
+ * Stop the servers a caller names, or all of them.
+ * @returns {{stopped: string[], remaining: number}}
+ */
+export function resetServers({ root, language } = {}) {
+  const stopped = [];
+  for (const [key, e] of [...servers]) {
+    if (root && e.root !== root) continue;
+    if (language && e.language !== language) continue;
+    stopped.push(key);
+    evict(key, "reset");
+  }
+  return { stopped, remaining: servers.size };
+}
+
+function keyFor(language, root) {
+  return `${language}:${root}`;
+}
+
+/**
+ * Run `fn` against a warm server for this root, one caller at a time.
+ *
+ * `fn` receives `{client, openDoc, root}`. It must not keep the client past its
+ * own return: the entry can be evicted the moment the lock is released.
+ */
+export async function withServer(spec, fn) {
+  const { language, root, bin, argv, initializeParams, initTimeoutMs = 120000 } = spec;
+  const key = keyFor(language, root);
+  startSweeper();
+
+  // Queue on this key before looking at anything. Reading the entry first and
+  // deciding whether to queue is the race: the decision is made on state that
+  // the call ahead is about to change.
+  const previous = locks.get(key) || Promise.resolve();
+  let release;
+  const mine = new Promise((r) => (release = r));
+  const chain = previous.then(
+    () => mine,
+    () => mine,
+  );
+  locks.set(key, chain);
+  await previous.catch(() => {});
+
+  try {
+    let entry = servers.get(key);
+    if (entry?.poisonedUntil && Date.now() < entry.poisonedUntil) {
+      return {
+        error: `ERROR: ${language} language server crashed ${CRASH_LIMIT}x in a minute for ${root}; not restarting until ${new Date(entry.poisonedUntil).toISOString()}. Last stderr: ${entry.lastStderr || "(none)"}`,
+      };
+    }
+    if (entry && !entry.client.alive) {
+      evict(key, "dead");
+      entry = undefined;
+    }
+    if (!entry) {
+      if (servers.size >= MAX_SERVERS) {
+        const oldest = [...servers.entries()]
+          .filter(([k]) => k !== key)
+          .sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
+        if (oldest) evict(oldest[0], "lru");
+      }
+      const started = await start({ key, language, root, bin, argv, initializeParams, initTimeoutMs });
+      if (started.error) return started;
+      entry = started;
+      servers.set(key, entry);
+    }
+    entry.lastUsed = Date.now();
+    const result = await fn({
+      client: entry.client,
+      root,
+      openDoc: (file) => openDoc(entry, file, language),
+    });
+    entry.lastUsed = Date.now();
+    return result;
+  } finally {
+    release();
+    // The queue outlives the server it guards unless the last caller clears it,
+    // and a key is added for every distinct root ever asked about - a slow leak
+    // in a server that runs for days. A later caller replaces the chain
+    // synchronously, before its first await, so a chain that is still ours
+    // means nobody is behind us.
+    if (locks.get(key) === chain) locks.delete(key);
+  }
+}
+
+async function start({ key, language, root, bin, argv, initializeParams, initTimeoutMs }) {
+  const prior = crashHistory.get(key);
+  const entry = {
+    language,
+    root,
+    openDocs: new Map(),
+    crashes: prior?.crashes || [],
+    poisonedUntil: prior?.poisonedUntil,
+    lastUsed: Date.now(),
+    lastStderr: prior?.lastStderr || "",
+  };
+  entry.client = createLspClient({
+    bin,
+    argv,
+    cwd: root,
+    initializeParams,
+    onCrash: (info) => {
+      // Mutate the entry in place. Replacing it with a copy broke identity with
+      // the `entry` an in-flight call is holding - its openDoc would go on
+      // writing to a record nothing else reads - and re-inserting it into the
+      // map resurrected a dead server that evict() had just removed.
+      entry.lastStderr = (info.stderr || "").trim().slice(-400);
+      const now = Date.now();
+      entry.crashes = [...entry.crashes.filter((t) => now - t < CRASH_WINDOW_MS), now];
+      if (entry.crashes.length >= CRASH_LIMIT) entry.poisonedUntil = now + POISON_MS;
+      // The crash record has to outlive the entry, or the poison window is lost
+      // the moment the dead entry is evicted.
+      crashHistory.set(key, { crashes: entry.crashes, poisonedUntil: entry.poisonedUntil, lastStderr: entry.lastStderr });
+    },
+  });
+  const init = await entry.client.initialize({ timeoutMs: initTimeoutMs });
+  if (init.error) {
+    try {
+      entry.client.dispose();
+    } catch {
+      /* ignore */
+    }
+    return { error: `ERROR: ${bin} failed to initialize: ${init.error.message}` };
+  }
+  return entry;
+}
+
+/**
+ * Make sure the server has this file, and has the version on disk.
+ *
+ * A stateless tool cannot track edits, so a file whose mtime moved is re-sent
+ * whole. `textDocumentSync.change: 2` means the server ACCEPTS incremental
+ * edits, not that it requires them.
+ */
+function openDoc(entry, file, language) {
+  let text;
+  let mtime;
+  try {
+    text = readFileSync(file, "utf8");
+    mtime = statSync(file).mtimeMs;
+  } catch (e) {
+    return { error: `ERROR: cannot read ${file}: ${e.message}` };
+  }
+  const uri = pathToFileURL(file).href;
+  const known = entry.openDocs.get(uri);
+  if (!known) {
+    entry.openDocs.set(uri, { mtime, version: 1 });
+    entry.client.notify("textDocument/didOpen", {
+      textDocument: { uri, languageId: language, version: 1, text },
+    });
+  } else if (known.mtime !== mtime) {
+    known.version += 1;
+    known.mtime = mtime;
+    entry.client.notify("textDocument/didChange", {
+      textDocument: { uri, version: known.version },
+      contentChanges: [{ text }],
+    });
+  }
+  return { uri, text };
+}

package/tools/code-intel/positions.js

@@ -0,0 +1,195 @@
+/**
+ * positions.js  -  the arithmetic, with no I/O and no processes.
+ *
+ * Everything here is a pure function, because everything here is the kind of
+ * mistake that produces a confident wrong answer rather than an error:
+ *
+ *   - LSP counts lines and characters from 0. Editors, ripgrep and every
+ *     citation in this pipeline count lines from 1. One off, and the tool
+ *     answers about the line above the one asked for, with no sign anything
+ *     went wrong.
+ *   - LSP `character` counts UTF-16 code units, not bytes and not code points.
+ *     A Turkish identifier or an emoji earlier in the line shifts every column
+ *     after it.
+ *   - A caller that has to count columns will get it wrong. `symbol` resolves a
+ *     name against the file's own symbol tree instead, which needs no build
+ *     configuration at all.
+ *
+ * @module tools/code-intel/positions
+ */
+
+/** Extensions this family can answer for, and which server answers. */
+export const LANGUAGE_BY_EXT = {
+  swift: "swift",
+  kt: "kotlin",
+  kts: "kotlin",
+};
+
+/**
+ * @param {string} file
+ * @returns {"swift"|"kotlin"|null}
+ */
+export function languageOf(file) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(file || "");
+  if (!m) return null;
+  return LANGUAGE_BY_EXT[m[1].toLowerCase()] || null;
+}
+
+/**
+ * A 1-based line/column, as a caller writes it, to an LSP position.
+ *
+ * @param {string} text    the file's contents
+ * @param {number} line    1-based
+ * @param {number} column  1-based, in characters
+ * @returns {{line: number, character: number}|{error: string}}
+ */
+export function toLspPosition(text, line, column) {
+  if (!Number.isInteger(line) || line < 1) return { error: `line ${line} is not a line number` };
+  const lines = text.split("\n");
+  if (line > lines.length) {
+    return { error: `line ${line} is past the end of the file (${lines.length} lines)` };
+  }
+  const col = Number.isInteger(column) && column >= 1 ? column : 1;
+  const src = lines[line - 1];
+  // Column counted in CHARACTERS by the caller, in UTF-16 units by LSP. Walk
+  // the code points rather than slicing, so an astral character counts 2.
+  let units = 0;
+  let seen = 0;
+  for (const ch of src) {
+    if (seen >= col - 1) break;
+    units += ch.length;
+    seen += 1;
+  }
+  return { line: line - 1, character: units };
+}
+
+/**
+ * An LSP position back to what a human reads.
+ *
+ * @param {string|null} text  the file's contents, when available
+ * @param {{line: number, character: number}} pos
+ * @returns {{line: number, column: number}} both 1-based
+ */
+export function fromLspPosition(text, pos) {
+  const line = (pos?.line ?? 0) + 1;
+  const units = pos?.character ?? 0;
+  if (typeof text !== "string") return { line, column: units + 1 };
+  const src = text.split("\n")[line - 1];
+  if (typeof src !== "string") return { line, column: units + 1 };
+  let consumed = 0;
+  let chars = 0;
+  for (const ch of src) {
+    if (consumed >= units) break;
+    consumed += ch.length;
+    chars += 1;
+  }
+  return { line, column: chars + 1 };
+}
+
+/**
+ * Find a symbol in a `textDocument/documentSymbol` result.
+ *
+ * Accepts either shape the spec allows: the hierarchical `DocumentSymbol[]`
+ * and the flat `SymbolInformation[]`. Matching is on the plain name or on a
+ * dotted path (`Greeter.greet`), so a caller can disambiguate without knowing
+ * the tree.
+ *
+ * Ambiguity is returned, never resolved: picking the first of two `reload`
+ * methods answers about the wrong one and looks identical to an answer about
+ * the right one.
+ *
+ * @returns {{match: object}|{candidates: object[]}|{error: string}}
+ */
+export function findSymbol(symbols, query) {
+  const wanted = String(query || "").trim();
+  if (!wanted) return { error: "no symbol given" };
+  const flat = [];
+  const walk = (nodes, prefix) => {
+    for (const s of nodes || []) {
+      if (!s || typeof s.name !== "string") continue;
+      const path = prefix ? `${prefix}.${s.name}` : s.name;
+      const range = s.selectionRange || s.range || s.location?.range;
+      flat.push({ name: s.name, path, kind: s.kind, range });
+      if (Array.isArray(s.children) && s.children.length) walk(s.children, path);
+    }
+  };
+  walk(Array.isArray(symbols) ? symbols : [], "");
+
+  const exactPath = flat.filter((s) => s.path === wanted);
+  const byName = flat.filter((s) => s.name === wanted);
+  const hits = exactPath.length ? exactPath : byName;
+
+  if (hits.length === 1) return { match: hits[0] };
+  if (hits.length > 1) return { candidates: hits };
+
+  const near = flat
+    .filter((s) => s.name.toLowerCase().includes(wanted.toLowerCase()))
+    .slice(0, 8);
+  return {
+    error: near.length
+      ? `no symbol named "${wanted}" in this file; nearest: ${near.map((n) => n.path).join(", ")}`
+      : `no symbol named "${wanted}" in this file`,
+  };
+}
+
+/**
+ * Turn LSP locations into something a caller can read, and cap them.
+ *
+ * The cap is load-bearing rather than tidy: a tool that declares an
+ * `outputSchema` skips this server's automatic large-payload offload, so
+ * nothing else stands between a common symbol's four thousand references and
+ * the caller's context.
+ */
+export function shapeLocations(locations, { root, maxResults = 200, readFile } = {}) {
+  const list = Array.isArray(locations) ? locations : locations ? [locations] : [];
+  const total = list.length;
+  const kept = list.slice(0, maxResults);
+  const cache = new Map();
+  const results = kept.map((loc) => {
+    const uri = loc.uri || loc.targetUri || "";
+    const range = loc.range || loc.targetSelectionRange || loc.targetRange || {};
+    const abs = uriToPath(uri);
+    let text = null;
+    if (typeof readFile === "function") {
+      if (!cache.has(abs)) cache.set(abs, readFile(abs));
+      text = cache.get(abs);
+    }
+    const start = fromLspPosition(text, range.start);
+    const out = {
+      file: root && abs.startsWith(root + "/") ? abs.slice(root.length + 1) : abs,
+      line: start.line,
+      column: start.column,
+    };
+    if (typeof text === "string") {
+      const src = text.split("\n")[start.line - 1];
+      if (typeof src === "string") out.preview = src.trim().slice(0, 200);
+    }
+    return out;
+  });
+  return { count: total, truncated: total > kept.length, results };
+}
+
+/** `file:///a/b` to `/a/b`, with percent-escapes undone. */
+export function uriToPath(uri) {
+  if (typeof uri !== "string") return "";
+  if (!uri.startsWith("file://")) return uri;
+  try {
+    return decodeURIComponent(uri.slice("file://".length));
+  } catch {
+    return uri.slice("file://".length);
+  }
+}
+
+/** The three legal shapes of `Hover.contents`, as one string. */
+export function markdownFromHover(contents) {
+  if (contents == null) return "";
+  if (typeof contents === "string") return contents;
+  if (Array.isArray(contents)) return contents.map(markdownFromHover).filter(Boolean).join("\n\n");
+  if (typeof contents === "object") {
+    if (typeof contents.value === "string") return contents.value;
+    if (typeof contents.language === "string" && typeof contents.value === "string") {
+      return contents.value;
+    }
+  }
+  return "";
+}