@niroai/niro 0.17.0 → 0.18.0

package/src/mcp/server.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * Niro MCP Server — stdio-to-SSE bridge.
+ * Niro MCP Server — stdio-to-HTTP bridge.
  *
- * Reads MCP JSON-RPC messages from stdin, forwards them to the
- * Niro ai-assistant SSE transport, and writes responses to stdout.
+ * Reads MCP JSON-RPC messages from stdin, forwards them to the Niro ai-assistant over
+ * Streamable HTTP (POST /mcp) or, on servers without it, the SSE transport (/mcp/sse),
+ * and writes responses to stdout.
  *
  * Required env vars:
  *   NIRO_API_KEY     — Your Niro API key (from console.niroai.dev)
@@ -13,6 +14,8 @@
  *   NIRO_MCP_SERVER_URL — ai-assistant base URL the bridge connects to
  *                         (default: https://aiassistant.niroai.dev). Falls back to
  *                         the `mcpServerUrl` field in ~/.niro/config.json.
+ *   NIRO_MCP_TRANSPORT  — http | sse | auto (default). auto uses Streamable HTTP (POST /mcp)
+ *                         when the server offers it, else the SSE transport (/mcp/sse).
  *
  * Project detection (in priority order):
  *   1. `.niro-project` file — walks up from process.cwd(); first non-comment line = project_id.
@@ -52,6 +55,11 @@ function niroProjectsFilePath() {
   return path.join(home, ".niro", "projects.json");
 }
 const { createPendingTracker, isTrackableRequest, resolveTimeoutMs } = require("../lib/pendingRequests");
+const { LocalBackend } = require("./localBackend");
+const integrationRequest = require("../lib/integrationRequest");
+const release = require("../lib/release");
+const localBuild = require("../lib/localBuild");
+const branchDrift = require("../lib/branchDrift");
 const { createImpactRecorder } = require("../lib/impactLog");
 
 // Evidence for the Edit|Write impact gate (docs/usecases/impact-gate.md): which impact tools this
@@ -343,19 +351,33 @@ function fatal(message) {
   process.exit(1);
 }
 
-if (!API_KEY && !CLI_TOKEN) {
+/**
+ * Local mode: see localSend. Read here because a cloud credential is not needed in it. A release without the cloud is
+ * always local mode, whatever the registration says: one registered by an earlier release carries no NIRO_MCP_MODE, and
+ * with no login it stopped at the credential check below before the engine was started (the checker's note 1 on
+ * fix/cli-small, 2026-11-06).
+ */
+const LOCAL_MODE = String(process.env.NIRO_MCP_MODE || "").toLowerCase() === "local" || !release.cloud;
+
+// Local mode answers without a credential: nothing is asked of the cloud to answer. The licence a
+// released engine needs is fetched with the login when there is one, and the engine itself says what
+// to do when there is none (verifier, 2026-11-02: this check used to stop local mode at start).
+if (!LOCAL_MODE && !API_KEY && !CLI_TOKEN) {
   fatal("No Niro credential found. Run `niro login` to authenticate (preferred), or set NIRO_API_KEY.");
 }
-process.stderr.write(
-  `[niro-mcp] Auth: ${CLI_TOKEN ? "CLI token (~/.niro/credentials.json)" : "NIRO_API_KEY"}\n`);
-if (PROJECT_ID) {
-  process.stderr.write(`[niro-mcp] Project: ${PROJECT_ID} (from ${PROJECT_ID_SOURCE})\n`);
-} else if (GIT_REMOTE) {
-  process.stderr.write(`[niro-mcp] Git remote detected: ${GIT_REMOTE} — server will auto-resolve project.\n`);
-} else {
+// What the bridge answers with, for whoever reads its log. Local mode uses none of it.
+if (!LOCAL_MODE) {
   process.stderr.write(
-    "[niro-mcp] No project detected — multi-project mode. Add a .niro-project file at the repo root (single line with project_id) or the Niro desktop agent will populate ~/.niro/projects.json.\n"
-  );
+    `[niro-mcp] Auth: ${CLI_TOKEN ? "CLI token (~/.niro/credentials.json)" : "NIRO_API_KEY"}\n`);
+  if (PROJECT_ID) {
+    process.stderr.write(`[niro-mcp] Project: ${PROJECT_ID} (from ${PROJECT_ID_SOURCE})\n`);
+  } else if (GIT_REMOTE) {
+    process.stderr.write(`[niro-mcp] Git remote detected: ${GIT_REMOTE} — server will auto-resolve project.\n`);
+  } else {
+    process.stderr.write(
+      "[niro-mcp] No project detected — multi-project mode. Add a .niro-project file at the repo root (single line with project_id) or the Niro desktop agent will populate ~/.niro/projects.json.\n"
+    );
+  }
 }
 
 const parsedUrl = new URL(API_URL);
@@ -404,6 +426,36 @@ const pending = createPendingTracker({
   onLog: (m) => process.stderr.write(`[niro-mcp] WARN: ${m}\n`),
 });
 
+/**
+ * The X-Niro-* identity headers every session carries: credential, bridge marker + version, project
+ * (or cwd) and the startup git context. Shared by the SSE GET and every Streamable HTTP request.
+ */
+function niroHeaders() {
+  const h = {};
+  if (CLI_TOKEN) h["X-Niro-Cli-Token"] = CLI_TOKEN;
+  if (API_KEY) h["X-Niro-Api-Key"] = API_KEY;
+  // Sent on every session so the server can spot an out-of-date install (see CLI_VERSION). The
+  // marker is what identifies THIS bridge: @niroai/mcp-server is a separate published bridge that
+  // hits the same /mcp/sse endpoint and sends neither header, so the server must not infer "old
+  // niro CLI" from a missing version alone — it would tell those users to upgrade a package they do
+  // not have installed, on every session, with no way to stop it.
+  h["X-Niro-Bridge"] = "niro-cli";
+  if (CLI_VERSION) h["X-Niro-Cli-Version"] = CLI_VERSION;
+  if (PROJECT_ID) {
+    h["X-Niro-Project-Id"] = PROJECT_ID;
+  } else {
+    h["X-Niro-Cwd"] = process.cwd();
+  }
+  // Git context on every session (see the SSE query params) so the freshness notice works for pinned projects too.
+  if (GIT_REMOTE) h["X-Niro-Git-Remote"] = GIT_REMOTE;
+  if (GIT_BRANCH) h["X-Niro-Git-Branch"] = GIT_BRANCH;
+  if (GIT_COMMIT) {
+    h["X-Niro-Git-Commit"] = GIT_COMMIT;
+    h["X-Niro-Git-Dirty"] = GIT_DIRTY ? "true" : "false";
+  }
+  return h;
+}
+
 /**
  * Connect to the SSE endpoint and listen for responses.
  *
@@ -450,28 +502,8 @@ function connectSse() {
 
     const sseHeaders = {
       "Accept": "text/event-stream",
+      ...niroHeaders(),
     };
-    if (CLI_TOKEN) sseHeaders["X-Niro-Cli-Token"] = CLI_TOKEN;
-    if (API_KEY) sseHeaders["X-Niro-Api-Key"] = API_KEY;
-    // Sent on every session so the server can spot an out-of-date install (see CLI_VERSION). The
-    // marker is what identifies THIS bridge: @niroai/mcp-server is a separate published bridge that
-    // hits the same /mcp/sse endpoint and sends neither header, so the server must not infer "old
-    // niro CLI" from a missing version alone — it would tell those users to upgrade a package they do
-    // not have installed, on every session, with no way to stop it.
-    sseHeaders["X-Niro-Bridge"] = "niro-cli";
-    if (CLI_VERSION) sseHeaders["X-Niro-Cli-Version"] = CLI_VERSION;
-    if (PROJECT_ID) {
-      sseHeaders["X-Niro-Project-Id"] = PROJECT_ID;
-    } else {
-      sseHeaders["X-Niro-Cwd"] = process.cwd();
-    }
-    // Git context on every session (see params above) so the freshness notice works for pinned projects too.
-    if (GIT_REMOTE) sseHeaders["X-Niro-Git-Remote"] = GIT_REMOTE;
-    if (GIT_BRANCH) sseHeaders["X-Niro-Git-Branch"] = GIT_BRANCH;
-    if (GIT_COMMIT) {
-      sseHeaders["X-Niro-Git-Commit"] = GIT_COMMIT;
-      sseHeaders["X-Niro-Git-Dirty"] = GIT_DIRTY ? "true" : "false";
-    }
 
     const req = httpModule.get(sseUrl, {
       headers: sseHeaders,
@@ -521,39 +553,7 @@ function connectSse() {
               resolve();
             }
           } else if (eventName === "message") {
-            // Swallow the response to an internally-replayed initialize (sentinel id) so the host
-            // never sees a duplicate initialize result after a transparent reconnect.
-            let swallowed = false;
-            let rewritten = null;
-            try {
-              const msg = JSON.parse(data);
-              // ADR-018 handshake: only an initialize result carries capabilities. When the server
-              // advertises niroTempProjectRouting, the bridge sends the folder pin as _niroPin (the
-              // server's routing ladder decides which project answers); otherwise it keeps injecting
-              // the pin as project_id — byte-identical pre-ADR-018 behaviour against old servers.
-              const exp = msg && msg.result && msg.result.capabilities
-                  && msg.result.capabilities.experimental;
-              // Presence check (truthy), not === true: the MCP spec requires experimental capability
-              // VALUES to be objects (a boolean fails the host's schema validation and kills the whole
-              // connection — found live), so the server sends {} and this must accept it.
-              if (exp && exp.niroTempProjectRouting && !routingCapable) {
-                routingCapable = true;
-                process.stderr.write("[niro-mcp] Server supports temp-project routing (_niroPin).\n");
-              }
-              if (msg && SWALLOW.has(msg.id)) {
-                SWALLOW.delete(msg.id);
-                swallowed = true;
-              } else {
-                // Cancel the client-side deadline when a delivered result matches an in-flight request.
-                pending.onIncoming(msg);
-                impact.noteResult(msg);
-                impact.touchAlive();
-                rewritten = captureReceipt(msg);
-              }
-            } catch (_) { /* not correlatable JSON — forward unchanged */ }
-            // captureReceipt returns a rewritten payload when it stripped the receipt field so the
-            // Stop hook can print it instead; otherwise the original bytes go through untouched.
-            if (!swallowed) process.stdout.write((rewritten || data) + "\n");
+            relayServerMessage(data);
           }
         }
       });
@@ -587,6 +587,49 @@ function connectSse() {
   });
 }
 
+/**
+ * Hand one server→client JSON-RPC message to the host (stdout), shared by both transports: detects the
+ * ADR-018 routing capability, swallows replayed-initialize replies, cancels the request deadline, feeds the
+ * impact gate and strips a disabled receipt. Returns the parsed message (null if it was not JSON).
+ */
+function relayServerMessage(data) {
+  // Swallow the response to an internally-replayed initialize (sentinel id) so the host
+  // never sees a duplicate initialize result after a transparent reconnect.
+  let swallowed = false;
+  let rewritten = null;
+  let msg = null;
+  try {
+    msg = JSON.parse(data);
+    // ADR-018 handshake: only an initialize result carries capabilities. When the server
+    // advertises niroTempProjectRouting, the bridge sends the folder pin as _niroPin (the
+    // server's routing ladder decides which project answers); otherwise it keeps injecting
+    // the pin as project_id — byte-identical pre-ADR-018 behaviour against old servers.
+    const exp = msg && msg.result && msg.result.capabilities
+        && msg.result.capabilities.experimental;
+    // Presence check (truthy), not === true: the MCP spec requires experimental capability
+    // VALUES to be objects (a boolean fails the host's schema validation and kills the whole
+    // connection — found live), so the server sends {} and this must accept it.
+    if (exp && exp.niroTempProjectRouting && !routingCapable) {
+      routingCapable = true;
+      process.stderr.write("[niro-mcp] Server supports temp-project routing (_niroPin).\n");
+    }
+    if (msg && SWALLOW.has(msg.id)) {
+      SWALLOW.delete(msg.id);
+      swallowed = true;
+    } else {
+      // Cancel the client-side deadline when a delivered result matches an in-flight request.
+      pending.onIncoming(msg);
+      impact.noteResult(msg);
+      impact.touchAlive();
+      rewritten = captureReceipt(msg);
+    }
+  } catch (_) { /* not correlatable JSON — forward unchanged */ }
+  // captureReceipt returns a rewritten payload when it stripped the receipt field so the
+  // Stop hook can print it instead; otherwise the original bytes go through untouched.
+  if (!swallowed) process.stdout.write((rewritten || data) + "\n");
+  return msg;
+}
+
 /**
  * Handle a lost SSE stream: mark reconnecting, drop the stale session (so POSTs during the gap
  * fail fast rather than hang), and start the reconnect loop. Guarded so overlapping 'end'/'error'
@@ -628,9 +671,9 @@ async function reconnectLoop() {
  * Replay the host's initialize on the freshly reconnected session so tools/call re-authenticate
  * (the server authenticates the session during initialize, not at SSE connect). The replay uses a
  * sentinel id whose response is swallowed (see SWALLOW) so the host never sees a second init
- * result. A no-op if the host has not initialized yet.
+ * result. A no-op if the host has not initialized yet. `send` is the transport's sender (SSE by default).
  */
-async function replayInitialize() {
+async function replayInitialize(send = sendMessage) {
   if (!initializeRaw) return;
   const reinit = JSON.parse(initializeRaw);
   // Negative sentinel id: JSON-RPC ids may be numbers, and host ids are small non-negative
@@ -638,9 +681,9 @@ async function replayInitialize() {
   const sentinelId = -(900000000 + (++reinitCounter));
   reinit.id = sentinelId;
   SWALLOW.add(sentinelId);
-  await sendMessage(reinit);
+  await send(reinit);
   // The initialized notification has no id/response; safe to (re)send after every init.
-  await sendMessage({ jsonrpc: "2.0", method: "notifications/initialized" });
+  await send({ jsonrpc: "2.0", method: "notifications/initialized" });
   process.stderr.write("[niro-mcp] Re-sent initialize on the new session.\n");
 }
 
@@ -795,10 +838,350 @@ function injectProjectId(message) {
   return message;
 }
 
+// --- Streamable HTTP transport (MCP 2025-03-26 / 2025-06-18) --------------------------------
+// One POST to ${API_URL}/mcp per host message; the server answers in that POST's own response —
+// application/json (one message) or text/event-stream (server messages, then the response). Any
+// ai-assistant task can serve any call, so there is no long-lived stream to babysit. Chosen by the host's initialize
+// when the server offers it (NIRO_MCP_TRANSPORT=http|sse forces one; default auto), else the SSE path
+// above runs unchanged. (Kept in lockstep with the standalone bridge — niro-mcp-server-npm/index.js.)
+const MCP_URL = `${API_URL}/mcp`;
+const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+const HTTP_RETRY_MS = 500;
+const HTTP_PROBE_TIMEOUT_MS = 10000;
+const HTTP_DELETE_TIMEOUT_MS = 2000;
+let httpSessionId = null;
+let httpProtocolVersion = null;
+let httpRenewing = null; // the in-flight session renewal, shared by every request that hit the 404
+let getStream = null;    // AbortController of the standalone GET stream
+
+function httpHeaders(sid, extra) {
+  const h = { ...niroHeaders(), ...extra };
+  if (sid) {
+    h["Mcp-Session-Id"] = sid;
+    if (httpProtocolVersion) h["MCP-Protocol-Version"] = httpProtocolVersion;
+  }
+  return h;
+}
+
+/** fetch() hides the useful part (ECONNREFUSED, ENOTFOUND, ...) in err.cause. */
+function netError(err) {
+  return (err && err.cause && (err.cause.code || err.cause.message)) || (err && err.message) || String(err);
+}
+
+function drain(res) {
+  if (res.body) res.body.cancel().catch(() => {});
+}
+
+// A failed POST is retried once only when that cannot run a call twice: the connection never opened
+// (nothing was sent), or the method is safe to repeat. A tools/call that may have reached the server
+// gets a JSON-RPC error instead — a second run could repeat its side effects.
+const NOT_SENT_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN"]);
+const SAFE_TO_REPEAT = new Set(["initialize", "ping", "tools/list", "resources/list", "prompts/list"]);
+
+function netCode(err) {
+  const c = err && err.cause;
+  return c && (c.code || (c.errors && c.errors[0] && c.errors[0].code)); // AggregateError: happy eyeballs
+}
+
+function retryable(err, method) {
+  const m = String(method || "");
+  return NOT_SENT_CODES.has(netCode(err)) || SAFE_TO_REPEAT.has(m) || m.startsWith("notifications/");
+}
+
+/** One POST, retried once after a short backoff on a network error when retryable() (never on an HTTP status). */
+async function httpPost(body, sid, method, signal) {
+  const opts = {
+    method: "POST",
+    body,
+    headers: httpHeaders(sid, { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" }),
+    signal,
+  };
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fetch(MCP_URL, opts);
+    } catch (err) {
+      if (attempt > 1 || !retryable(err, method)) {
+        throw new Error(`could not reach ${MCP_URL}: ${netError(err)}${attempt > 1 ? "" : " (not retried: it may have reached the server)"}`);
+      }
+      process.stderr.write(`[niro-mcp] POST /mcp failed (${netError(err)}); retrying once\n`);
+      await sleep(HTTP_RETRY_MS);
+    }
+  }
+}
+
+/** Yields the data of each SSE `message` event in order (an event with no name is a message, per spec). */
+async function* sseMessages(body) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of body) {
+    buffer = (buffer + decoder.decode(chunk, { stream: true })).replace(/\r\n/g, "\n");
+    let end;
+    while ((end = buffer.indexOf("\n\n")) !== -1) {
+      const block = buffer.slice(0, end);
+      buffer = buffer.slice(end + 2);
+      let eventName = "message";
+      const dataLines = [];
+      for (const line of block.split("\n")) {
+        if (line.startsWith("event:")) eventName = line.slice(6).trim();
+        else if (line.startsWith("data:")) dataLines.push(line.slice(5));
+      }
+      const data = dataLines.join("\n").trim();
+      if (eventName === "message" && data) yield data;
+    }
+  }
+}
+
+/**
+ * The engine on this machine, started on the first call that needs it.
+ *
+ * Not at startup: most sessions are in a cloud-indexed folder and would pay for an engine they
+ * never ask anything, and a machine with no engine must not have a failure at connect.
+ */
+const localBackend = new LocalBackend();
+
 /**
- * Main: connect SSE, then read stdin line by line and forward to server.
+ * Is this session's folder answered by the engine on this machine?
+ *
+ * Asked once per process and remembered. The answer cannot change without a command being run
+ * in that folder, and `localBuild.isLocallyIndexed` already caches it per folder and answers
+ * "not local" for a machine with no engine, which is what keeps every existing customer on the
+ * cloud path.
  */
-async function main() {
+let locality = null;
+
+/** Whether the branch notice has been given in this session. One line, once. */
+let driftSaid = false;
+
+async function answeredLocally() {
+  if (locality === null) {
+    locality = await localBuild.isLocallyIndexed(process.cwd());
+    if (locality) {
+      process.stderr.write(
+        "[niro-mcp] This folder is indexed locally; tool calls are answered on this machine\n");
+    }
+  }
+  return locality;
+}
+
+/**
+ * Answer a `tools/call` from the local graph, and write the result to stdout.
+ *
+ * Returns true when it answered, false when the call should go to the cloud after all. Nothing
+ * here can throw: a failure of the local engine becomes a tool result saying so, because an
+ * exception in the bridge would look to the assistant like the whole server died.
+ *
+ * `initialize` and `tools/list` are deliberately NOT routed here. The cloud answers both, so
+ * the assistant sees one toolset whichever graph is behind it, and a tool the local graph
+ * cannot serve says so when it is called (Niraj, 2026-10-14).
+ */
+async function answerLocally(message) {
+  const toolName = message.params && message.params.name;
+  if (!toolName) return false;
+  const started = Date.now();
+  let result;
+  try {
+    await localBackend.start();
+    if (!localBackend.serves(toolName)) {
+      result = LocalBackend.cannotServe(toolName);
+    } else {
+      result = await localBackend.call(toolName, (message.params || {}).arguments || {});
+    }
+  } catch (err) {
+    // The engine would not start, was refused a licence, or did not answer. Said as a tool
+    // result rather than an error: an assistant reads a result and can act on it, while a
+    // JSON-RPC error reads as the server being broken.
+    result = {
+      content: [
+        {
+          type: "text",
+          text:
+            "The local engine could not answer: " + ((err && err.message) || String(err)) +
+            "\n\nThis folder is indexed on this machine, so nothing was asked of the cloud. " +
+            "Check it with:  " + (release.cloud ? "niro-local status" : "niro status"),
+        },
+      ],
+      isError: true,
+    };
+  }
+  // A `niro mcp receipt --off` line was already taken out of a mark_task_complete answer by
+  // `localBackend.call` (LocalBackend.withoutLine), before anything was added in front of it.
+  // Said once per session, in front of the first local answer: the folders of this project
+  // may have moved onto different branches since they were attached, which no guard can
+  // prevent and which makes every answer crossing them suspect. Asked for lazily and never
+  // allowed to fail an answer.
+  if (!driftSaid) {
+    driftSaid = true;
+    try {
+      const said = await branchDrift.noticeFor(process.cwd());
+      if (said) result = LocalBackend.prepend(result, said);
+    } catch (err) {
+      process.stderr.write(`[niro-mcp] branch check skipped: ${err.message}\n`);
+    }
+  }
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, result }) + "\n");
+  impact.noteResult({ jsonrpc: "2.0", id: message.id, result });
+  // The edit hook reads this to know the bridge is answering; the cloud path writes it on each reply.
+  impact.touchAlive();
+  // The engine says, on the first tool call of a session, when its graph is behind the files.
+  // Act on it instead of only passing it along: the watcher normally rebuilds, and on a machine
+  // where the watcher is not running nobody else will. After the answer is written, so the
+  // assistant waits for nothing, and local folders only.
+  localBuild.catchUpIfBehind(process.cwd(), result, {
+    log: (line) => process.stderr.write(`[niro-mcp] ${line}\n`),
+  });
+  process.stderr.write(
+    `[niro-mcp] local ${toolName} answered in ${Date.now() - started}ms\n`);
+  return true;
+}
+
+/**
+ * POST one message on `sid` and relay everything the server answers to stdout, in order. Returns the
+ * response to `message` (null for a notification). Throws when there is no answer — the caller turns that
+ * into a JSON-RPC error for the host. A 404 on a session throws with `sessionGone` set.
+ * `probe` (auto mode's first initialize): any non-2xx throws before anything is relayed, and the POST is
+ * time-bounded, so the caller can fall back to SSE and run the same initialize there.
+ */
+async function postAndRelay(message, sid, probe = false) {
+  const signal = probe ? AbortSignal.timeout(HTTP_PROBE_TIMEOUT_MS) : undefined;
+  const res = await httpPost(JSON.stringify(injectProjectId(message)), sid, message.method, signal);
+  if (res.status === 404 && sid) {
+    drain(res);
+    throw Object.assign(new Error("Niro session expired (HTTP 404)"), { sessionGone: true });
+  }
+  const isInit = message.method === "initialize";
+  const newSid = isInit && res.ok && res.headers.get("mcp-session-id");
+  if (newSid) {
+    // Adopted BEFORE the reply is relayed: the host answers it with notifications/initialized at once.
+    httpSessionId = newSid;
+    httpProtocolVersion = res.headers.get("mcp-protocol-version");
+    process.stderr.write(`[niro-mcp] Session established: ${newSid}\n`);
+  }
+  const trackable = isTrackableRequest(message);
+  if (res.status === 202) {
+    drain(res);
+    return null;
+  }
+  if (!res.ok && probe) {
+    drain(res);
+    throw new Error(`Streamable HTTP not available (HTTP ${res.status})`);
+  }
+  if (!res.ok) {
+    // The server may answer with its own JSON-RPC error (e.g. 503 session store down): relay that.
+    const text = (await res.text().catch(() => "")).trim();
+    let msg = null;
+    try { msg = JSON.parse(text); } catch (_) {}
+    if (trackable && msg && msg.error && msg.id === message.id) return relayServerMessage(text);
+    throw new Error(`HTTP ${res.status} from ${MCP_URL}`);
+  }
+  let reply = null;
+  const note = (msg) => {
+    if (msg && msg.id === message.id && (msg.result !== undefined || msg.error !== undefined)) reply = msg;
+  };
+  if ((res.headers.get("content-type") || "").includes("text/event-stream")) {
+    try {
+      for await (const data of sseMessages(res.body)) note(relayServerMessage(data));
+    } catch (err) {
+      if (!reply) throw err; // a drop after the answer arrived costs nothing
+    }
+  } else {
+    const text = (await res.text()).trim();
+    if (text) note(relayServerMessage(text));
+  }
+  if (trackable && !reply) throw new Error("the server closed the response without answering");
+  if (newSid) {
+    if (!httpProtocolVersion) {
+      httpProtocolVersion = (reply && reply.result && reply.result.protocolVersion)
+        || (message.params && message.params.protocolVersion) || DEFAULT_PROTOCOL_VERSION;
+    }
+    openGetStream(newSid).catch((err) => process.stderr.write(`[niro-mcp] GET /mcp stream failed: ${err.message}\n`));
+  }
+  return reply;
+}
+
+/**
+ * Forward one host message over Streamable HTTP. A 404 on the session means the server forgot it
+ * (TTL, restart): renew it once by replaying the host's initialize, then resend; a second failure throws.
+ */
+async function httpSend(message) {
+  if (message.method === "initialize") return postAndRelay(message, null);
+  if (httpRenewing) await httpRenewing.catch(() => {});
+  const sid = httpSessionId;
+  try {
+    return await postAndRelay(message, sid);
+  } catch (err) {
+    if (!err.sessionGone) throw err;
+    process.stderr.write("[niro-mcp] Streamable HTTP session expired; re-initializing\n");
+    await renewHttpSession(sid);
+    return postAndRelay(message, httpSessionId);
+  }
+}
+
+function renewHttpSession(staleSid) {
+  if (httpRenewing) return httpRenewing;
+  if (httpSessionId !== staleSid) return Promise.resolve(); // another request already renewed it
+  httpSessionId = null;
+  routingCapable = false; // re-detected from the replayed initialize, as on an SSE reconnect
+  httpRenewing = replayInitialize((m) => postAndRelay(m, m.method === "initialize" ? null : httpSessionId))
+    .finally(() => { httpRenewing = null; });
+  return httpRenewing;
+}
+
+/**
+ * The optional standalone GET stream for server-initiated notifications. 405 = the server has none
+ * (skip silently); 404 = the session is gone (the next POST renews it and reopens this). A drop
+ * reopens with backoff for as long as the session lives.
+ */
+async function openGetStream(sid) {
+  if (getStream) getStream.abort();
+  const ctrl = new AbortController();
+  getStream = ctrl;
+  const log = (m) => process.stderr.write(`[niro-mcp] GET /mcp stream ${m}\n`);
+  let backoff = RECONNECT_INITIAL_BACKOFF_MS;
+  while (httpSessionId === sid && !ctrl.signal.aborted) {
+    let why = "closed";
+    try {
+      // fetch resolves at the response headers; the server may hold them until its first event.
+      log("opening");
+      const res = await fetch(MCP_URL, {
+        headers: httpHeaders(sid, { "Accept": "text/event-stream" }),
+        signal: ctrl.signal,
+      });
+      if (res.status === 405) { log("not offered by the server (HTTP 405)"); return drain(res); }
+      if (res.status === 404) { log("not opened: session gone (HTTP 404); the next call renews it"); return drain(res); }
+      if (res.ok) {
+        log("opened");
+        backoff = RECONNECT_INITIAL_BACKOFF_MS;
+        for await (const data of sseMessages(res.body)) relayServerMessage(data);
+      } else {
+        why = `refused (HTTP ${res.status})`;
+        drain(res);
+      }
+    } catch (err) {
+      why = `dropped (${netError(err)})`;
+    }
+    if (ctrl.signal.aborted || httpSessionId !== sid) return log("closed (session ended)");
+    log(`${why}; reopening in ${backoff}ms`);
+    await sleep(backoff);
+    backoff = Math.min(backoff * 2, RECONNECT_MAX_BACKOFF_MS);
+  }
+}
+
+/** Best-effort end of a session; never blocks shutdown for long. */
+async function deleteHttpSession(sid) {
+  try {
+    drain(await fetch(MCP_URL, {
+      method: "DELETE", headers: httpHeaders(sid), signal: AbortSignal.timeout(HTTP_DELETE_TIMEOUT_MS) }));
+  } catch (_) { /* best effort */ }
+}
+
+/** Streamable HTTP chosen: `send` is httpSend, and the session is ended on SIGTERM too. */
+function useHttpTransport() {
+  process.on("SIGTERM", shutdown);
+  return httpSend;
+}
+
+/** SSE chosen: connect (fatal on failure, as always), start the liveness watchdog; `send` is sendMessage. */
+async function useSseTransport() {
   try {
     await connectSse();
   } catch (err) {
@@ -819,7 +1202,126 @@ async function main() {
     }
   }, Math.max(5000, Math.floor(SSE_LIVENESS_MS / 3)));
   if (typeof watchdog.unref === "function") watchdog.unref();
+  return sendMessage;
+}
+
+/**
+ * auto mode: the host's own initialize decides the transport — no throwaway probe session. It goes to
+ * POST /mcp first; anything but a 2xx (404/405 from an old server or with the flag off, a 5xx, an
+ * unreachable /mcp, a timeout) relays nothing, so SSE is connected and that same initialize runs there.
+ * The host sees exactly one initialize response. Messages that arrive meanwhile wait for the choice.
+ */
+let chosenSend = null; // Promise<send> once the first message started the choice
+async function autoSend(message) {
+  if (chosenSend) return (await chosenSend)(message);
+  let choose;
+  chosenSend = new Promise((r) => (choose = r));
+  if (message.method === "initialize") {
+    try {
+      const reply = await postAndRelay(message, null, true);
+      process.stderr.write(`[niro-mcp] Transport: streamable-http (${MCP_URL})\n`);
+      choose(useHttpTransport());
+      return reply;
+    } catch (err) {
+      httpSessionId = null;
+      if (getStream) getStream.abort();
+      process.stderr.write(`[niro-mcp] ${err.message}; using SSE\n`);
+    }
+  }
+  const send = await useSseTransport();
+  process.stderr.write("[niro-mcp] Transport: sse\n");
+  choose(send);
+  return send(message);
+}
+
+/**
+ * Local mode (`niro mcp install --local` registers the bridge with NIRO_MCP_MODE=local): every request is
+ * answered by the engine on this machine and nothing is sent to the cloud, initialize and tools/list
+ * included, so the assistant sees the tools niro-local actually serves. Tool calls take the same path as
+ * a locally indexed folder in cloud mode (answerLocally: the impact record, the receipt, the catch-up
+ * build). Anything else is answered here and written the way a relayed answer is.
+ */
+async function localSend(message) {
+  // Notifications have no answer. The engine was sent its own `initialized` when it started.
+  if (message.id === undefined || message.id === null) return;
+  const answer = (body) => {
+    const reply = { jsonrpc: "2.0", id: message.id, ...body };
+    pending.clear(message.id);
+    impact.noteResult(reply);
+    impact.touchAlive();
+    process.stdout.write(JSON.stringify(reply) + "\n");
+  };
+  try {
+    if (message.method === "initialize") return answer({ result: await localBackend.initialize(message.params) });
+    // niro-cli's own tool after the engine's: asking Niro to support a language, framework or tool. The engine
+    // never goes on the network, so the bridge answers it (src/lib/integrationRequest.js).
+    if (message.method === "tools/list") {
+      const listed = await localBackend.listTools();
+      return answer({ result: { ...listed, tools: [...((listed && listed.tools) || []), integrationRequest.TOOL] } });
+    }
+    if (message.method === "ping") return answer({ result: {} });
+    if (message.method === "tools/call") {
+      pending.clear(message.id);
+      if (await answerLocally(message)) return;
+    }
+    return answer({ result: await localBackend.request(message.method, message.params) });
+  } catch (err) {
+    // An engine that will not start must not make the assistant drop the whole server: the handshake and an
+    // empty tool list are answered here, and the log says why (kept from the plan-page release's offline answer).
+    if (message.method === "initialize" || message.method === "tools/list") {
+      process.stderr.write(`[niro-mcp] the local engine did not start: ${err.message}\n`);
+      if (message.method === "tools/list") return answer({ result: { tools: [] } });
+      return answer({
+        result: {
+          protocolVersion: (message.params && message.params.protocolVersion) || "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "niro", version: require("../../package.json").version },
+        },
+      });
+    }
+    // The engine's own error code when it gave one (-32601 for a method it does not know).
+    const code = Number.isInteger(err && err.code) ? err.code : -32603;
+    return answer({ error: { code, message: `The local engine could not answer: ${err.message}` } });
+  }
+}
+
+/** Main: forced transport (NIRO_MCP_TRANSPORT=http|sse) or auto, then read stdin and forward to the server. */
+async function main() {
+  // Two ways to the same path, and both answer every request from the engine on this machine with nothing sent to a
+  // server: a release without the cloud (src/lib/release.js, decided 2026-11-05), and local mode chosen in a cloud
+  // release (`niro mcp install --local`, Niraj 2026-11-02). Every tool call goes to the engine, a folder it does not
+  // know included, so a new git worktree gets the engine's own answer and its temporary copy rather than a "not
+  // indexed" reply from here (Niraj, 2026-11-06, Q6).
+  if (!release.cloud || LOCAL_MODE) {
+    locality = true;
+    process.stderr.write(
+      release.cloud
+        ? "[niro-mcp] Local mode: every request is answered by niro-local on this machine\n"
+        : "[niro-mcp] Local engine only: answered on this machine\n"
+    );
+    return serveStdio(localSend);
+  }
+  const forced = String(process.env.NIRO_MCP_TRANSPORT || "").toLowerCase();
+  if (forced === "http" || forced === "sse") {
+    process.stderr.write(`[niro-mcp] Transport: ${forced === "http" ? `streamable-http (${MCP_URL})` : "sse"}`
+      + " (forced by NIRO_MCP_TRANSPORT)\n");
+    return serveStdio(forced === "http" ? useHttpTransport() : await useSseTransport());
+  }
+  serveStdio(autoSend);
+}
+
+// Streamable HTTP: end the server session (best effort, short timeout) before exiting.
+let closing = false;
+async function shutdown() {
+  if (closing) return;
+  closing = true;
+  if (getStream) getStream.abort();
+  if (httpSessionId) await deleteHttpSession(httpSessionId);
+  process.exit(0);
+}
 
+/** Read host messages from stdin line by line and forward each with `send` (the chosen transport). */
+function serveStdio(send) {
   const rl = readline.createInterface({
     input: process.stdin,
     terminal: false,
@@ -839,15 +1341,40 @@ async function main() {
 
     // Remember the host's initialize so we can replay it verbatim to re-authenticate a fresh
     // session after a transparent reconnect.
-    if (message.method === "initialize") initializeRaw = line;
+    if (message.method === "initialize") {
+      initializeRaw = line;
+      // Which assistant this is, for the engine's journal (agent_name), before the engine starts.
+      localBackend.setClient(message.params && message.params.clientInfo);
+    }
     impact.noteRequest(message);
 
     // Arm the deadline for a real request before sending; a delivered result (or the
     // send-failure path below) cancels it.
     const trackable = isTrackableRequest(message);
     if (trackable) pending.arm(message.id);
+
+    // niro-cli's own tool (request_integration) is answered here in every mode: it is not the engine's and not the
+    // cloud's, and it sends nothing without the user's confirm.
+    if (message.method === "tools/call" && message.params && message.params.name === integrationRequest.TOOL.name) {
+      if (trackable) pending.clear(message.id);
+      const reply = { jsonrpc: "2.0", id: message.id, result: await integrationRequest.callTool(message.params.arguments || {}) };
+      impact.noteResult(reply);
+      process.stdout.write(JSON.stringify(reply) + "\n");
+      return;
+    }
+
+    // The routing decision, and the only place it is taken: a tool call in a locally indexed
+    // folder is answered here and never reaches the cloud, so a customer's code and their
+    // questions about it stay on their machine. Everything else, including `initialize` and
+    // `tools/list`, goes to the cloud exactly as it did before.
+    if (message.method === "tools/call" && (await answeredLocally())) {
+      if (trackable) pending.clear(message.id);
+      if (await answerLocally(message)) return;
+      if (trackable) pending.arm(message.id);
+    }
+
     try {
-      await sendMessage(message);
+      await send(message);
     } catch (err) {
       process.stderr.write(`[niro-mcp] Failed to send message: ${err.message}\n`);
       // The attempt still counts for the impact gate: a server that cannot be reached must not leave
@@ -866,12 +1393,16 @@ async function main() {
     }
   });
 
-  rl.on("close", () => {
-    process.exit(0);
-  });
+  rl.on("close", shutdown);
   // A bridge that is gone must not keep the impact gate denying edits for up to 30 minutes on the
   // strength of a stale alive marker. A hard kill still leaves it; the hook ages it out.
-  process.on("exit", () => impact.clearAlive());
+  process.on("exit", () => {
+    impact.clearAlive();
+    // The engine is this process's child, so it would die with the bridge anyway; stopping it
+    // explicitly also stops the licence renewal timer, which is what keeps a command from
+    // hanging around waiting for one.
+    localBackend.stop();
+  });
 }
 
 main();