@niroai/niro 0.16.0 → 0.18.0

package/src/mcp/localBackend.js

@@ -0,0 +1,751 @@
+/**
+ * The bridge's other backend: the engine on this machine.
+ *
+ * One bridge, two backends, chosen per call (Niraj, 2026-10-14). A folder indexed by the local
+ * engine is answered from the graph on this machine; everything else goes to the cloud exactly
+ * as before. This file is the local half: it starts the engine's own MCP server as a child,
+ * speaks MCP to it, and answers one tool call at a time.
+ *
+ * **Why speak MCP to it rather than add a one-shot command to the engine.** A process per call
+ * would pay the engine's startup and its database connection on every question, and three
+ * things that only exist within a session would be lost: the licence, which arrives on a pipe
+ * and is renewed while the process lives; the once-per-session notice saying the graph is
+ * behind; and the journal, which records a session rather than a pile of unrelated calls.
+ *
+ * **The lease travels the same way it does for a build.** The child is started with the two
+ * extra pipes and `lease.attach` serves it, so a released engine is licensed for as long as the
+ * editor is connected. That is the MCP half of the licence work, and it is why this module
+ * starts the engine rather than the engine starting itself.
+ *
+ * **Every tool stays advertised** (Niraj: "agreed that's the best approach"). The host's
+ * `tools/list` is still answered by the cloud, so the assistant sees one toolset. A tool the
+ * local graph cannot serve answers in one line saying so and what to run, rather than
+ * disappearing from the list mid-session or returning an empty result that reads like "there
+ * is nothing there".
+ */
+const { spawn } = require("child_process");
+
+const lease = require("../lib/lease");
+const localEngine = require("../lib/localEngine");
+const receiptStore = require("../lib/receiptStore");
+const lineName = require("./lineName");
+
+/**
+ * Cloud names that the engine serves under a different one.
+ *
+ * Kept small and explicit on purpose. The cloud now accepts `resolve_name` as an alias of its
+ * own (phase 1 of the local-engine plan), so the vocabulary is converging; this is the other
+ * direction, for a host that calls the cloud's name.
+ */
+const ALIASES = { resolve_fqn: "resolve_name" };
+
+/**
+ * The cloud's argument names, and the engine's name for the same thing.
+ *
+ * **Why this is needed.** The host is given the CLOUD's schema, because `tools/list` is
+ * answered by the cloud so that the assistant sees one toolset whichever graph is behind it.
+ * The arguments that arrive are therefore the cloud's, and the cloud names the thing being
+ * asked about after its kind: `method_fqn` for a method, `class_fqn` for a class, `fqn`,
+ * `entity_fqn` and `resource_fqn`. The engine calls it `name` in every tool. Nothing
+ * translated between the two, so the engine's own argument validation refused the call before
+ * the graph was touched: measured over stdio on 2026-10-16, `get_call_chain` with
+ * `method_fqn` answered "1 validation error ... name Field required" and the same question with
+ * `name` answered in full. Nine of the engine's eighteen tools failed that way and they are the
+ * structural core, which is why a locally indexed folder produced no call chain, no blast radius
+ * and no resolve at all.
+ *
+ * Keyed by the name the host called AND by the engine's own name where the two differ, because
+ * an editor connected straight to `niro-local mcp` sends the engine's names instead.
+ *
+ * **The order of the keys is the order of precedence**, for a host that sends two seeds at
+ * once. A method before a class, because the narrower question is the one that was asked: a
+ * blast radius for one method is not the blast radius of its whole class.
+ *
+ * An argument the engine does not declare is ignored by it rather than refused, which is why
+ * only a missing required one broke a call and why nothing here has to drop the rest.
+ */
+const ARGUMENT_NAMES = {
+  resolve_fqn: { entity_fqn: "name" },
+  resolve_name: { entity_fqn: "name" },
+  // Not transitive_depth: the engine reads it under that name, with upstream's meaning, since
+  // niro-local's call-chain rewrite of 2026-10-23. Renamed to `depth` it meant something else
+  // on the reverse chain, where upstream's `depth` is not an alias.
+  get_call_chain: { method_fqn: "name" },
+  get_reverse_call_chain: { method_fqn: "name", class_fqn: "name" },
+  get_blast_radius: { method_fqn: "name", class_fqn: "name", event_fqn: "name" },
+  get_class_structure: { class_fqn: "name" },
+  get_exception_flow: { method_fqn: "name" },
+  // Not get_event_producers_and_handlers: the cloud's `type` there is 'producers' | 'handlers'
+  // | 'both', the side to return (ai-assistant GetEventProducersAndHandlersMcpTool.java:42-44),
+  // not an event name. Renamed to `name`, `type: "producers"` asked the engine for an event
+  // called "producers" and was told there was none. The engine reads `type` itself since
+  // niro-local 9beca43.
+  find_handler: { fqn: "name" },
+  get_data_resource_usage: { resource_fqn: "name" },
+};
+
+/**
+ * The cloud's batch forms. The engine answers one name per call, so these are answered one at
+ * a time and the answers joined, rather than refused: a host that asks about every method of a
+ * client class in one call is doing the right thing, and the engine is local, so the extra
+ * calls cost a few milliseconds each.
+ */
+const BATCH_NAMES = ["method_fqns", "class_fqns", "entity_fqns", "fqns", "targets"];
+
+/**
+ * How many of a batch are answered. A cap because the answers are concatenated and an
+ * assistant's context is the scarce thing; said in the answer when it bites, so nobody is left
+ * believing they saw the lot.
+ */
+const BATCH_LIMIT = 10;
+
+/**
+ * The tools whose question can be asked by route instead of by name, and what the engine needs
+ * instead.
+ *
+ * The cloud resolves a route to its handler for you: `get_call_chain` says it "accepts
+ * method_fqn (partial auto-resolves) or http_path", and `get_blast_radius` says http_path
+ * "resolves to handler method automatically". The engine resolves a NAME, so an untranslated
+ * route arrived as a missing `name` and the call was refused, which is the same error this file
+ * exists to remove (measured by an independent verifier on 2026-10-16: 3 of 3 refused). The
+ * engine does hold the answer, under `find_api_endpoints`, so the route is turned into its
+ * handler's name first and the real question asked about that.
+ */
+const BY_ROUTE = ["get_call_chain", "get_reverse_call_chain", "get_blast_radius"];
+
+/**
+ * One line of the form the engine's own endpoint list is rendered in
+ * (`niro-local/src/niro_local/mcp/server.py` `_render_endpoints`, which writes
+ * `1. POST /api/orders/ -> com.shop.OrderController.create`). Read from there rather than from
+ * a sample answer, so a change to that renderer is a change to one regular expression here.
+ */
+const ENDPOINT_LINE = /^\s*\d+\.\s+(\S+)\s+(\S+)\s+->\s+(.+?)\s*$/;
+
+/**
+ * Arguments the engine does not have, and what the answer therefore is NOT.
+ *
+ * Said in the answer rather than dropped in silence. An argument the engine ignores is
+ * normally harmless, because the engine's answer is a superset or the argument only shapes the
+ * cloud's presentation (`purpose`, `rationale`), and a notice for those would be noise on every
+ * call. These are the ones where ignoring the argument changes what the answer MEANS, so a
+ * reader who is not told draws a false conclusion: asked for callers, `get_exception_flow`
+ * answers the downstream flow and looks like an answer; asked for upstream only,
+ * `get_blast_radius` includes the downstream half as well; asked for three of something, a list
+ * the engine does not page returns all of it.
+ */
+
+const NOT_HONOURED = {
+  get_exception_flow: {
+    direction: (value) => {
+      const asked = String(value).toLowerCase();
+      return asked === "upstream" || asked === "callers"
+        ? "the local graph answers the downstream flow only, so this is where the exceptions " +
+            "reach from here, not what reaches this method"
+        : null;
+    },
+    exception_type: () => "the local graph does not filter this flow by exception type",
+  },
+  get_blast_radius: {
+    direction: (value) => {
+      const asked = String(value).toLowerCase();
+      return asked === "upstream" || asked === "downstream"
+        ? "the local graph answers both directions at once, so the other half is in here too"
+        : null;
+    },
+    include_source_code: () =>
+      "the local graph holds structure and not source text, so no source is included",
+  },
+};
+
+/**
+ * A notice is only worth saying when the argument would have changed the answer.
+ *
+ * `purpose` and `rationale` shape the cloud's presentation and nothing else, so they get no
+ * notice: one on every call is noise, and noise is read as decoration. Nor does an argument
+ * the engine honours anyway, which is why each entry decides from the VALUE: asked for both
+ * directions, the engine's blast radius is exactly the answer, and a notice there would be
+ * wrong as well as noisy.
+ */
+function notHonoured(toolName, args) {
+  const table = NOT_HONOURED[toolName];
+  if (!table) return null;
+  const said = [];
+  for (const [argument, decide] of Object.entries(table)) {
+    if (!(argument in args) || args[argument] === undefined || args[argument] === null) continue;
+    const sentence = decide(args[argument]);
+    if (sentence && !said.includes(sentence)) said.push(sentence);
+  }
+  if (said.length === 0) return null;
+  return `NOTE FROM niro: ${said.join("; and ")}.`;
+}
+
+/** How long to wait for the engine to answer one call before giving up on it. */
+const CALL_TIMEOUT_MS = Number(process.env.NIRO_LOCAL_CALL_TIMEOUT_MS) || 30_000;
+
+/** How long to wait for the engine to start and list its tools. */
+const START_TIMEOUT_MS = Number(process.env.NIRO_LOCAL_START_TIMEOUT_MS) || 30_000;
+
+/** Said at the top of every local answer, so nobody has to guess which graph answered. */
+const LOCAL_MARKER = "Answered from the local graph on this machine (niro-local).";
+
+/**
+ * One line of text that is an end-of-task line: `[NIRO-CLI] ...` from the engine (`[NIRO-LOCAL] ...`
+ * from an engine older than 2026-11-09, `lineName.js`), `[NIRO] ...` from the cloud, with spaces or a
+ * backtick allowed in front. Tested on each line from its start
+ * only, so what follows it (a backtick, a Windows "\r") and the layout around it do not matter.
+ */
+const NIRO_LINE = new RegExp(`^[ \\t]*\`?${lineName.PREFIX_SOURCE} `);
+/**
+ * How the engine's own notices open (niro-local `freshness.py`: "NOTE FROM niro-local: the graph is
+ * behind ...", "... ACTION REQUIRED ..."; `arguments.py`: "⚠ This call also passed ..."). Kept when
+ * the line is taken out; "NOTE FROM niro-local:" is also what starts the background rebuild
+ * (localBuild.js BEHIND_MARKER).
+ */
+const NOTICE_OPENINGS = ["NOTE FROM", "⚠"];
+/** Said in place of the line when `niro mcp receipt --off` is set. */
+const LINE_SWITCHED_OFF =
+  "The end-of-task Niro line is switched off on this machine, so there is no line to show. Print nothing.";
+
+class LocalBackend {
+  constructor({ log = (line) => process.stderr.write(`[niro-mcp] ${line}\n`) } = {}) {
+    this.log = log;
+    this.child = null;
+    this.licence = null;
+    this.tools = null;
+    this.client = null;
+    // The host's own initialize is passed to the engine, and the engine's answers to it and to tools/list are
+    // handed back to the host unchanged (`localSend` in server.js: local mode, and every release without the cloud).
+    this.hostInitialize = null;
+    this.initializeResult = null;
+    this.toolList = null;
+    this.nextId = 1;
+    this.waiting = new Map();
+    this.buffered = "";
+    this.starting = null;
+  }
+
+  /** Remember the assistant's `clientInfo`, passed on to the engine when it starts. */
+  setClient(info) {
+    if (info && typeof info.name === "string" && info.name) {
+      this.client = { name: info.name.slice(0, 100), version: String(info.version || "").slice(0, 50) };
+    }
+  }
+
+  /** Start the engine and learn which tools it serves. Safe to call repeatedly. */
+  async start() {
+    // `starting` first: the child exists from the first moment of _start, before the engine has
+    // answered initialize and tools/list, so a call arriving meanwhile must wait for that, not find
+    // `tools` still empty (local mode sends initialize, tools/list and a call back to back).
+    if (this.starting) return this.starting;
+    if (this.child && !this.child.killed) return this.tools;
+    this.starting = this._start().finally(() => {
+      this.starting = null;
+    });
+    return this.starting;
+  }
+
+  async _start() {
+    const executable = localEngine.enginePath();
+    // Marked in use while it runs, so an upgrade does not delete its folder under it (`engine.startHeld`).
+    const child = require("../lib/engine").startHeld(executable, () =>
+      spawn(executable, ["mcp"], {
+        // Three pipes for MCP itself plus the two the licence travels on, which is why the
+        // engine is started here and not by the editor: only the CLI can fetch a licence.
+        stdio: ["pipe", "pipe", "pipe", "pipe", "pipe"],
+        env: lease.childEnvironment(),
+      })
+    );
+    this.child = child;
+    this.licence = lease.attach(child, { log: (line) => this.log(line.trim()) });
+
+    child.stdout.on("data", (chunk) => this._onData(chunk));
+    // The engine's standard error is its own log, not an answer. Passed through to ours so a
+    // refusal or a database problem is visible to whoever is reading the bridge's log.
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString().trim();
+      if (text) this.log(`engine: ${text}`);
+    });
+    child.on("error", (problem) => this._fail(`could not start the engine: ${problem.message}`));
+    // An engine that exits at once (a refused licence, a broken binary) closes its input before the handshake is
+    // written to it, and the write fails with EPIPE. Node reports that as an event on this pipe, and with no listener
+    // it is thrown and the whole bridge dies without answering anything. Failing the waiting calls instead lets
+    // localSend (server.js) answer the handshake with an empty tool list, as it does for a missing engine.
+    child.stdin.on("error", (problem) => {
+      if (this.child === child) this._fail(`the engine closed its input (${problem.code || problem.message})`);
+    });
+    child.on("close", (code) => {
+      this._fail(`the engine stopped (exit ${code})`);
+      this.child = null;
+      this.tools = null;
+    });
+
+    this.initializeResult = await this._send("initialize", this.hostInitialize || {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      // The assistant's own name and version, from its handshake with the bridge, so the engine's
+      // journal records which assistant asked (agent_name); the bridge's when there was none.
+      clientInfo: this.client || { name: "niro-cli-bridge", version: require("../../package.json").version },
+    }, START_TIMEOUT_MS);
+    // A notification, so there is nothing to wait for.
+    this._write({ jsonrpc: "2.0", method: "notifications/initialized" });
+    const listed = await this._send("tools/list", {}, START_TIMEOUT_MS);
+    // The line's name as the developer sees it, whichever engine answered (`lineName.js`).
+    this.initializeResult = lineName.initializeRenamed(this.initializeResult);
+    this.toolList = lineName.toolsRenamed(listed.tools || []);
+    this.tools = new Set(this.toolList.map((tool) => tool.name));
+    this.log(`the local engine serves ${this.tools.size} tool(s)`);
+    return this.tools;
+  }
+
+  /**
+   * Local mode: the engine's answer to the host's initialize. The engine is started with the host's
+   * own parameters, so the protocol version and capabilities are agreed between the two directly.
+   */
+  async initialize(params) {
+    if (!this.child && !this.starting && params) this.hostInitialize = params;
+    await this.start();
+    return this.initializeResult;
+  }
+
+  /** Local mode: the engine's tool list, exactly as it gave it. */
+  async listTools() {
+    await this.start();
+    return { tools: this.toolList || [] };
+  }
+
+  /** Local mode: any other request (resources/list, prompts/list ...), passed to the engine as it is. */
+  async request(method, params) {
+    await this.start();
+    return this._send(method, params || {}, CALL_TIMEOUT_MS);
+  }
+
+  /** Does the local engine serve this tool, under this name or an alias of it? */
+  serves(toolName) {
+    if (!this.tools) return false;
+    return this.tools.has(toolName) || this.tools.has(ALIASES[toolName]);
+  }
+
+  /**
+   * Answer one `tools/call`.
+   *
+   * Three things happen to the call on the way through, and each has its own reason above:
+   * the bridge's own extras are dropped, because the pin and the git snapshot exist for the
+   * cloud's routing ladder and the engine answers for the folder it runs in; the cloud's
+   * argument names become the engine's; and a question asked about several names is asked
+   * once per name.
+   */
+  async call(toolName, args = {}) {
+    await this.start();
+    const passed = { ...args };
+    for (const extra of ["_niroPin", "_niroGit", "_niroGitRepos", "project_id"]) {
+      delete passed[extra];
+    }
+    // Every call goes to the tool the host named. Until 2026-10-23 a get_call_chain asked for
+    // callers was sent to get_reverse_call_chain, because the engine had no `direction`; it
+    // answers that itself now, in upstream's wording.
+    const wanted = toolName;
+    const renamed = LocalBackend.engineArguments(wanted, passed);
+    const name = this.tools.has(wanted) ? wanted : ALIASES[wanted];
+    const notice = notHonoured(toolName, passed);
+
+    // A question asked by route: the engine answers by name, so find the name first.
+    if (!("name" in renamed) && renamed.http_path && BY_ROUTE.includes(wanted)) {
+      const handler = await this._handlerFor(String(renamed.http_path));
+      if (!handler) return this._withMarker(LocalBackend.noRoute(String(renamed.http_path)));
+      renamed.name = handler;
+    }
+    delete renamed.http_path;
+
+    const batch = LocalBackend.batchOf(renamed);
+    const answer = batch
+      ? await this._callEach(name, renamed, batch)
+      : await this._send("tools/call", { name, arguments: renamed }, CALL_TIMEOUT_MS);
+    // `niro mcp receipt --off`: the engine has run the tool, so the turn is recorded; the line it
+    // returned is taken out here, before the bridge adds anything of its own, so everything in
+    // the answer is the engine's. Read on every call, so switching it takes effect at the next
+    // mark_task_complete with no restart.
+    const kept =
+      wanted === "mark_task_complete" && receiptStore.isDisabled() ? LocalBackend.withoutLine(answer) : answer;
+    // An engine older than 2026-11-09 writes `[NIRO-LOCAL]`; the developer is shown `[NIRO-CLI]`. Only the
+    // line's own answer is renamed throughout; any other answer only in the reminder under it (`lineName.js`).
+    const shown =
+      wanted === "mark_task_complete"
+        ? lineName.answerRenamed(kept)
+        : lineName.answerRenamed(kept, lineName.reminderRenamed);
+    const marked = this._withMarker(shown);
+    return notice ? LocalBackend.prepend(marked, notice) : marked;
+  }
+
+  /**
+   * The method that answers a route, asked of the engine's own endpoint list.
+   *
+   * Exact path first, then a path that only differs by a trailing slash, then the single match
+   * when the engine found exactly one. Null when the route is not in the graph, or when the
+   * engine does not serve the endpoint list at all, because a guess here would send the real
+   * question to the wrong method and the answer would look right.
+   */
+  async _handlerFor(httpPath) {
+    const tool = "find_api_endpoints";
+    if (!this.tools || !this.tools.has(tool)) return null;
+    let text;
+    try {
+      const answer = await this._send(
+        "tools/call",
+        { name: tool, arguments: { path_pattern: httpPath } },
+        CALL_TIMEOUT_MS
+      );
+      text = (answer.content || [])
+        .filter((block) => block && block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    } catch {
+      return null;
+    }
+    const rows = [];
+    for (const line of String(text || "").split("\n")) {
+      const found = ENDPOINT_LINE.exec(line);
+      if (found) rows.push({ path: found[2], handler: found[3] });
+    }
+    const bare = (one) => one.replace(/\/+$/, "");
+    const exact = rows.find((row) => row.path === httpPath)
+      || rows.find((row) => bare(row.path) === bare(httpPath));
+    if (exact) return exact.handler;
+    return rows.length === 1 ? rows[0].handler : null;
+  }
+
+  /** What to answer when the route is not one this folder serves. */
+  static noRoute(httpPath) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Nothing in this folder's graph serves ${httpPath}, so the question was not ` +
+            "answered.\n\nRoutes are read from the annotations and decorators a method " +
+            "carries, so a route registered at run time is not in the graph. " +
+            "find_api_endpoints lists the routes this folder does serve; ask again with the " +
+            "method's name once you have it.",
+        },
+      ],
+    };
+  }
+
+
+  /**
+   * The same arguments under the names the engine declares.
+   *
+   * A name the engine already uses wins over a translated one, so a host that sends both
+   * `name` and `method_fqn` is not overwritten by the second. A batch key is dropped when a
+   * single name is present, because the single name is the more specific question.
+   */
+  static engineArguments(toolName, args) {
+    const map = ARGUMENT_NAMES[toolName];
+    const out = { ...args };
+    if (map) {
+      for (const [cloud, engine] of Object.entries(map)) {
+        if (cloud in out && !(engine in out)) {
+          out[engine] = out[cloud];
+        }
+        delete out[cloud];
+      }
+    }
+    if ("name" in out) {
+      for (const key of BATCH_NAMES) delete out[key];
+    }
+    return out;
+  }
+
+  /** The batch key in use and the names under it, or null when this is an ordinary call. */
+  static batchOf(args) {
+    for (const key of BATCH_NAMES) {
+      const names = args[key];
+      if (Array.isArray(names) && names.length > 0) return { key, names };
+    }
+    return null;
+  }
+
+  /**
+   * Ask the same question about each name and join the answers.
+   *
+   * One text block per name, each under the name it answers for, because a run of answers with
+   * nothing between them cannot be read. A name that fails is reported in its own place rather
+   * than failing the whole call: nine answers and one failure is a better answer than none.
+   */
+  async _callEach(name, args, batch) {
+    const { key, names } = batch;
+    const asked = names.slice(0, BATCH_LIMIT);
+    const rest = { ...args };
+    delete rest[key];
+    const parts = [];
+    let failures = 0;
+    for (const one of asked) {
+      let text;
+      try {
+        const answer = await this._send(
+          "tools/call",
+          { name, arguments: { ...rest, name: one } },
+          CALL_TIMEOUT_MS
+        );
+        text = (answer.content || [])
+          .filter((block) => block && block.type === "text")
+          .map((block) => block.text)
+          .join("\n");
+      } catch (err) {
+        failures += 1;
+        text = `could not be answered: ${(err && err.message) || String(err)}`;
+      }
+      parts.push(`## ${one}\n\n${text}`);
+    }
+    if (names.length > asked.length) {
+      parts.push(
+        `The first ${BATCH_LIMIT} of ${names.length} names are answered above. Ask again for ` +
+          "the rest, or ask about one name at a time."
+      );
+    }
+    // Every name failed, so this is a failed call and not an answer that happens to contain
+    // the word "could not": a host that reads isError retries or says so, and one that reads
+    // the text alone is no worse off.
+    const answer = { content: [{ type: "text", text: parts.join("\n\n") }] };
+    if (failures > 0 && failures === asked.length) answer.isError = true;
+    return answer;
+  }
+
+  /**
+   * Which graph answered, said in the answer itself.
+   *
+   * Risk 1 of the plan: the two graphs name some things differently, so an answer that does
+   * not say where it came from is the most expensive kind of wrong. One line, prepended to the
+   * first text block.
+   */
+  _withMarker(answer) {
+    return LocalBackend.prepend(answer, LOCAL_MARKER);
+  }
+
+  /**
+   * Put `text` in front of an answer's first text block, or add one when it has none.
+   *
+   * Static and shared because two things do this now: the marker saying which graph answered,
+   * and the notice about a project whose folders are on different branches. A second copy of
+   * this would be a second shape of answer for a host to render.
+   */
+  static prepend(answer, text) {
+    const content = Array.isArray(answer && answer.content) ? answer.content : [];
+    const first = content.find((block) => block && block.type === "text");
+    if (!first) {
+      return { ...answer, content: [{ type: "text", text }, ...content] };
+    }
+    return {
+      ...answer,
+      content: content.map((block) =>
+        block === first ? { ...block, text: `${text}\n\n${block.text}` } : block
+      ),
+    };
+  }
+
+  /**
+   * The engine's `mark_task_complete` answer with the end-of-task line taken out, for a developer
+   * who ran `niro mcp receipt --off`. Given the engine's answer as it came, before the bridge adds
+   * its marker.
+   *
+   * The engine still ran the tool, so the turn is recorded in its journal; only what the assistant
+   * would print is removed, the way the switch already works for the cloud's answer
+   * (`captureReceipt`). The engine's answer is what to do with the line, then the line, then any
+   * notes (niro-local `receipt.with_instruction(line) + note`). So everything before the first line
+   * is the instruction and goes, whatever its wording, except a paragraph that is one of the
+   * engine's own notices ("NOTE FROM niro-local: ...", "⚠ ..."): the assistant must still read
+   * those, and the bridge starts a background rebuild on "the graph is behind" (`catchUpIfBehind`).
+   * Every line goes; what follows the last line (a "Not recorded" note) stays. One sentence, said once, replaces them, so the assistant does not
+   * go looking for a line. Lines are found one at a time, so a trailing newline, one newline instead
+   * of a blank line, Windows line endings or backticks around the line make no difference.
+   *
+   * `structuredContent.result` is a second copy of the same text (niro-local declares an output
+   * schema for this tool, and a client may show that copy instead), so it is given the same text.
+   * A `result` that is not a string is left alone: niro-local always sends a string (its tools
+   * return text), so there is no other shape to clean, and guessing at one could break a client
+   * that checks the copy against the schema. An answer with no line comes back as it was.
+   */
+  static withoutLine(answer) {
+    const content = Array.isArray(answer && answer.content) ? answer.content : null;
+    if (!content) return answer;
+    const first = content.findIndex((block) => LocalBackend._isText(block) && LocalBackend._lineAt(block.text) >= 0);
+    if (first < 0) return answer;
+    const blocks = [];
+    content.forEach((block, index) => {
+      if (!LocalBackend._isText(block)) return blocks.push(block);
+      const lines = block.text.split("\n");
+      // Before the first line: the instruction, which goes, and any engine notice, which stays.
+      const before = index < first ? lines : index === first ? lines.slice(0, LocalBackend._lineAt(block.text)) : [];
+      const notices = LocalBackend._notices(before);
+      if (index < first) {
+        if (notices.length) blocks.push({ ...block, text: notices.join("\n\n") });
+        return;
+      }
+      const after = index === first ? lines.slice(LocalBackend._lineAt(block.text) + 1) : lines;
+      const rest = after.filter((line) => !NIRO_LINE.test(line));
+      while (rest.length && !rest[0].trim()) rest.shift();
+      while (rest.length && !rest[rest.length - 1].trim()) rest.pop();
+      const tail = rest.join("\n");
+      if (index === first) {
+        const parts = [...notices, LINE_SWITCHED_OFF, ...(tail.trim() ? [tail] : [])];
+        blocks.push({ ...block, text: parts.join("\n\n") });
+      } else if (tail.trim()) {
+        blocks.push({ ...block, text: tail });
+      }
+    });
+    const cleaned = { ...answer, content: blocks };
+    const structured = answer.structuredContent;
+    if (structured && typeof structured === "object" && typeof structured.result === "string") {
+      cleaned.structuredContent = {
+        ...structured,
+        result: blocks.filter(LocalBackend._isText).map((block) => block.text).join("\n\n"),
+      };
+    }
+    return cleaned;
+  }
+
+  /**
+   * The paragraphs of `lines` that are engine notices, in order. A paragraph is a run of lines
+   * between blank lines; it is a notice when its first line opens with one of NOTICE_OPENINGS.
+   */
+  static _notices(lines) {
+    const paragraphs = [];
+    let current = [];
+    for (const line of [...lines, ""]) {
+      if (line.trim()) {
+        current.push(line);
+      } else if (current.length) {
+        paragraphs.push(current);
+        current = [];
+      }
+    }
+    return paragraphs
+      .filter((paragraph) => NOTICE_OPENINGS.some((opening) => paragraph[0].trimStart().startsWith(opening)))
+      .map((paragraph) => paragraph.join("\n"));
+  }
+
+  /** A content block with text in it. */
+  static _isText(block) {
+    return Boolean(block && block.type === "text" && typeof block.text === "string");
+  }
+
+  /** The index of the first end-of-task line in `text`, split at "\n", or -1. */
+  static _lineAt(text) {
+    return text.split("\n").findIndex((line) => NIRO_LINE.test(line));
+  }
+
+  /** What to answer for a tool the local graph cannot serve. */
+  static cannotServe(toolName) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `${toolName} is not answered for this folder: it is indexed locally by niro-local, ` +
+            "whose graph holds structure and not source text or documentation.\n\n" +
+            "What you can do instead: read the file with your own tools, and use " +
+            "list_types, resolve_name, get_call_chain, get_reverse_call_chain, " +
+            "get_blast_radius, get_class_structure, find_api_endpoints, find_handler, " +
+            "get_exception_flow, list_events, get_event_producers_and_handlers, " +
+            "find_outbound_http_calls, list_data_resources, get_data_resource_usage or " +
+            "get_service_topology, which this graph does answer.",
+        },
+      ],
+    };
+  }
+
+  /** Stop the engine. The licence stops with it. */
+  stop() {
+    if (this.licence) this.licence.stop();
+    if (this.child && !this.child.killed) {
+      try {
+        this.child.kill();
+      } catch {
+        // Already gone.
+      }
+    }
+    this.child = null;
+    this.tools = null;
+  }
+
+  // --- the JSON-RPC plumbing ---------------------------------------------------------
+
+  _write(message) {
+    if (!this.child || !this.child.stdin.writable) {
+      throw new Error("the local engine is not running");
+    }
+    this.child.stdin.write(JSON.stringify(message) + "\n");
+  }
+
+  _send(method, params, timeoutMs) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.waiting.delete(id);
+        reject(new Error(`the local engine did not answer ${method} within ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.waiting.set(id, { resolve, reject, timer });
+      try {
+        this._write({ jsonrpc: "2.0", id, method, params });
+      } catch (problem) {
+        clearTimeout(timer);
+        this.waiting.delete(id);
+        reject(problem);
+      }
+    });
+  }
+
+  _onData(chunk) {
+    this.buffered += chunk.toString();
+    let newline = this.buffered.indexOf("\n");
+    while (newline !== -1) {
+      const line = this.buffered.slice(0, newline).trim();
+      this.buffered = this.buffered.slice(newline + 1);
+      if (line) this._onLine(line);
+      newline = this.buffered.indexOf("\n");
+    }
+  }
+
+  _onLine(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      // The engine writes JSON-RPC on this pipe and nothing else, so anything unparseable is
+      // worth saying rather than ignoring: it is usually a library printing to the wrong place.
+      this.log(`the local engine wrote something that is not JSON-RPC: ${line.slice(0, 120)}`);
+      return;
+    }
+    const pending = this.waiting.get(message.id);
+    if (!pending) return; // a notification, or an answer to a call that already timed out
+    this.waiting.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.error) {
+      const refused = new Error(message.error.message || "the local engine refused the call");
+      refused.code = message.error.code;
+      pending.reject(refused);
+    } else {
+      pending.resolve(message.result || {});
+    }
+  }
+
+  /** Every waiting call fails when the engine goes away, rather than hanging for ever. */
+  _fail(reason) {
+    for (const [, pending] of this.waiting) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(reason));
+    }
+    this.waiting.clear();
+  }
+}
+
+module.exports = {
+  LocalBackend,
+  ALIASES,
+  notHonoured,
+  ARGUMENT_NAMES,
+  BATCH_NAMES,
+  BATCH_LIMIT,
+  LOCAL_MARKER,
+  LINE_SWITCHED_OFF,
+  CALL_TIMEOUT_MS,
+};