@gamaze/hicortex 0.20.2 → 0.20.4

package/assets/viz.html

@@ -80,6 +80,68 @@
     background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim);
   }
 
+  /* ---- account menu (#365) ---- */
+  /* Dropdown under the nav account element: token reveal/copy, connect
+     snippets, plan & billing, sign-out. The wrapper (#nav-account) becomes
+     the positioning context; the panel is absolute + right-aligned under it,
+     above graph content (the topbar is z-10, the panel gets 60 within it). */
+  .hc-nav-account { position: relative; }
+  .acct-trigger {
+    display: inline-flex; align-items: center; gap: 6px;
+    background: transparent; color: var(--text); border: none; border-radius: 6px;
+    padding: 4px 8px; font: inherit; cursor: pointer;
+  }
+  .acct-trigger:hover { background: rgba(128,128,128,0.15); }
+  .acct-caret { color: var(--text-dim); font-size: 10px; }
+  .acct-menu {
+    display: none; position: absolute; top: calc(100% + 8px); right: 0;
+    min-width: 320px; max-width: min(420px, calc(100vw - 40px));
+    background: var(--panel); border: 1px solid var(--panel-border); border-radius: 8px;
+    padding: 12px; z-index: 60;
+    box-shadow: 0 8px 24px rgba(0,0,0,0.35);
+    color: var(--text); font-size: 13px; text-align: left;
+  }
+  .acct-menu.open { display: block; }
+  .acct-label {
+    font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em;
+    color: var(--text-dim); margin: 8px 0 4px;
+  }
+  .acct-menu .acct-label:first-child { margin-top: 0; }
+  .acct-token-row { display: flex; align-items: center; gap: 6px; }
+  .acct-token {
+    flex: 1; min-width: 0;
+    font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    background: var(--bg); border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 4px 8px; color: var(--text);
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .acct-btn {
+    background: var(--panel); color: var(--text);
+    border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 4px 10px; font: inherit; font-size: 12px; cursor: pointer;
+  }
+  .acct-btn:hover { border-color: var(--accent); color: var(--accent); }
+  .acct-btn:disabled { opacity: 0.5; cursor: default; }
+  .acct-menu details { border-top: 1px solid var(--panel-border); margin-top: 10px; padding-top: 8px; }
+  .acct-menu summary { cursor: pointer; color: var(--text-dim); font-size: 13px; }
+  .acct-menu summary:hover { color: var(--accent); }
+  .acct-snippet { margin-bottom: 8px; }
+  .acct-snippet pre {
+    background: var(--bg); border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 8px; margin: 4px 0;
+    font: 11.5px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    white-space: pre-wrap; word-break: break-all;
+    max-height: 200px; overflow-y: auto;
+  }
+  .acct-link {
+    display: block; width: 100%; text-align: left;
+    background: transparent; border: none; border-radius: 4px;
+    color: var(--text); font: inherit; font-size: 13px;
+    padding: 6px 8px; cursor: pointer;
+  }
+  .acct-link:hover { background: rgba(128,128,128,0.15); }
+  .acct-link.acct-danger:hover { color: var(--danger); }
+
   /* ---- left control panel ---- */
   #panel {
     position: fixed; top: 48px; left: 12px; width: 236px;
@@ -385,28 +447,43 @@
   });
 
   // =========================================================================
-  // Account identity in the nav — GET /account (the lightweight endpoint, the
-  // same shape the dashboard payload carries). Fail-soft: 401/fetch error
-  // leaves the span empty (fetchGraph owns the 401 token prompt); an all-null
-  // account (self-hosted default) renders nothing. textContent only — this
-  // page uses innerHTML exclusively for the escaped 3D-force-graph tooltips.
+  // Account identity in the nav + the ACCOUNT MENU (#365) — GET /account (the
+  // lightweight endpoint, the same shape the dashboard payload carries).
+  // Fail-soft: 401/fetch error leaves the span empty (fetchGraph owns the 401
+  // token prompt); an all-null account (self-hosted default) renders nothing —
+  // no menu either. createElement/textContent only — this page uses innerHTML
+  // exclusively for the escaped 3D-force-graph tooltips.
   // =========================================================================
   function renderAccount(a) {
     var host = document.getElementById("nav-account");
     if (!host) return;
     host.textContent = "";
     if (!a || (a.name === null && a.org === null && a.plan === null)) return;
+    var trigger = document.createElement("button");
+    trigger.type = "button";
+    trigger.id = "acct-trigger";
+    trigger.className = "acct-trigger";
+    trigger.setAttribute("aria-haspopup", "menu");
+    trigger.setAttribute("aria-expanded", "false");
     var who = [a.name, a.org].filter(function (s) { return typeof s === "string" && s !== ""; });
     who.forEach(function (s, i) {
-      if (i > 0) host.appendChild(document.createTextNode(" · "));
-      host.appendChild(document.createTextNode(s));
+      if (i > 0) trigger.appendChild(document.createTextNode(" · "));
+      trigger.appendChild(document.createTextNode(s));
     });
     if (typeof a.plan === "string" && a.plan !== "") {
       var pill = document.createElement("span");
       pill.className = "plan";
       pill.textContent = a.plan;
-      host.appendChild(pill);
+      trigger.appendChild(pill);
     }
+    var caret = document.createElement("span");
+    caret.className = "acct-caret";
+    caret.setAttribute("aria-hidden", "true");
+    caret.textContent = "▾";
+    trigger.appendChild(caret);
+    host.appendChild(trigger);
+    host.appendChild(buildAcctMenu());
+    wireAcctMenu();
   }
   function loadAccount() {
     var headers = {};
@@ -417,6 +494,273 @@
       .catch(function () { /* leave the span empty — nav is never worth an error */ });
   }
 
+  // =========================================================================
+  // Account menu (#365) — dropdown under the nav account element: token
+  // reveal/copy, connect snippets, plan & billing, sign-out. The token shown
+  // is AUTHORITATIVE server truth: a lazy GET /account/token on the FIRST
+  // open (echo-only endpoint — the fetch already proves the caller holds the
+  // token). localStorage is NEVER trusted for the display: it can be stale
+  // after token rotation and is absent entirely for browser sessions the
+  // hosted router authenticates via its session→bearer injection. On fetch
+  // failure the row fails explicitly ("token unavailable", actions disabled).
+  // Built with createElement/textContent only (page convention).
+  // =========================================================================
+  var acctToken = null;             // token from /account/token (server truth)
+  var acctTokenState = "unfetched"; // "unfetched" | "ok" | "unavailable"
+  var acctTokenFetched = false;     // one lazy fetch attempt per page load
+  var acctRevealed = false;         // unmasked while the menu is open
+
+  function maskToken(t) {
+    // hctx-••••••23f9 — first 5 chars + 6 bullets + last 4. Real tokens are
+    // hctx-<32hex>; the guard keeps a degenerate short token from leaking.
+    if (typeof t !== "string" || t.length < 10) return "••••••••••";
+    return t.slice(0, 5) + "••••••" + t.slice(-4);
+  }
+
+  function el(tag, id, cls, text) {
+    var n = document.createElement(tag);
+    if (id) n.id = id;
+    if (cls) n.className = cls;
+    if (text !== undefined) n.textContent = text;
+    return n;
+  }
+
+  // Static menu skeleton — token-dependent values fill in renderAcctToken().
+  function buildAcctMenu() {
+    var menu = el("div", "acct-menu", "acct-menu");
+    menu.appendChild(el("div", null, "acct-label", "Connection token"));
+    var row = el("div", null, "acct-token-row");
+    row.appendChild(el("code", "acct-token-val", "acct-token", "…"));
+    row.appendChild(el("button", "acct-reveal", "acct-btn", "Reveal"));
+    row.appendChild(el("button", "acct-copy-token", "acct-btn", "Copy"));
+    menu.appendChild(row);
+    var details = el("details", "acct-connect");
+    details.appendChild(el("summary", null, null, "Connect an agent"));
+    details.appendChild(el("div", null, "acct-label", "CLI"));
+    var snip1 = el("div", null, "acct-snippet");
+    snip1.appendChild(el("pre", "acct-cli"));
+    snip1.appendChild(el("button", "acct-copy-cli", "acct-btn", "Copy"));
+    details.appendChild(snip1);
+    details.appendChild(el("div", null, "acct-label", "MCP — ~/.claude.json"));
+    var snip2 = el("div", null, "acct-snippet");
+    snip2.appendChild(el("pre", "acct-mcp"));
+    snip2.appendChild(el("button", "acct-copy-mcp", "acct-btn", "Copy"));
+    details.appendChild(snip2);
+    menu.appendChild(details);
+    menu.appendChild(el("button", "acct-plan", "acct-link", "Plan & billing"));
+    menu.appendChild(el("button", "acct-signout", "acct-link acct-danger", "Sign out"));
+    // All menu buttons are type=button (never submit — no form here, but the
+    // page's convention is explicit types).
+    var btns = menu.querySelectorAll("button");
+    for (var i = 0; i < btns.length; i++) btns[i].type = "button";
+    return menu;
+  }
+
+  // The connect line: server URL + token on ONE line, space-separated.
+  function acctConnectLine() {
+    return location.origin + " " + acctToken;
+  }
+
+  // CLI snippet — init has NO --token flag; it prompts interactively. The
+  // comment mirrors init.ts's own printed hint ("When prompted for the token,
+  // paste: …").
+  function acctCliText() {
+    return "# When prompted for the token, paste: " + acctToken +
+      "\nnpx @gamaze/hicortex init --server " + location.origin;
+  }
+
+  // MCP snippet — mirrors EXACTLY what runClientInit writes into
+  // ~/.claude.json (init.ts): SSE transport at <origin>/sse with a bearer
+  // Authorization header.
+  function acctMcpText() {
+    return JSON.stringify({
+      mcpServers: {
+        hicortex: {
+          type: "sse",
+          url: location.origin + "/sse",
+          headers: { Authorization: "Bearer " + acctToken }
+        }
+      }
+    }, null, 2);
+  }
+
+  function renderAcctToken() {
+    var val = document.getElementById("acct-token-val");
+    if (!val) return; // menu not rendered (self-hosted all-null account)
+    var revealBtn = document.getElementById("acct-reveal");
+    var copyToken = document.getElementById("acct-copy-token");
+    var copyCli = document.getElementById("acct-copy-cli");
+    var copyMcp = document.getElementById("acct-copy-mcp");
+    var cli = document.getElementById("acct-cli");
+    var mcp = document.getElementById("acct-mcp");
+    if (acctTokenState !== "ok") {
+      val.textContent = acctTokenState === "unfetched" ? "…" : "token unavailable";
+      revealBtn.disabled = true;
+      copyToken.disabled = true;
+      copyCli.disabled = true;
+      copyMcp.disabled = true;
+      cli.textContent = acctTokenState === "unfetched" ? "" : "token unavailable";
+      mcp.textContent = acctTokenState === "unfetched" ? "" : "token unavailable";
+      return;
+    }
+    revealBtn.disabled = false;
+    copyToken.disabled = false;
+    copyCli.disabled = false;
+    copyMcp.disabled = false;
+    val.textContent = acctRevealed ? acctToken : maskToken(acctToken);
+    revealBtn.textContent = acctRevealed ? "Hide" : "Reveal";
+    cli.textContent = acctCliText();
+    mcp.textContent = acctMcpText();
+  }
+
+  function fetchAcctToken() {
+    if (acctTokenFetched) return;
+    acctTokenFetched = true;
+    var headers = {};
+    if (token) headers["Authorization"] = "Bearer " + token; // same as loadAccount
+    fetch("/account/token", { headers: headers })
+      .then(function (resp) {
+        if (!resp.ok) throw new Error("HTTP " + resp.status);
+        return resp.json();
+      })
+      .then(function (data) {
+        if (typeof data.token !== "string" || !data.token) throw new Error("bad payload");
+        acctToken = data.token;
+        acctTokenState = "ok";
+        renderAcctToken();
+      })
+      .catch(function () {
+        acctTokenState = "unavailable"; // fail explicitly — no localStorage fallback
+        renderAcctToken();
+      });
+  }
+
+  function closeAcctMenu() {
+    var menu = document.getElementById("acct-menu");
+    if (!menu) return;
+    menu.classList.remove("open");
+    var trigger = document.getElementById("acct-trigger");
+    if (trigger) trigger.setAttribute("aria-expanded", "false");
+    // Masked again + connect section collapsed on EVERY close (locked design).
+    acctRevealed = false;
+    var details = document.getElementById("acct-connect");
+    if (details) details.removeAttribute("open");
+    renderAcctToken();
+  }
+
+  function openAcctMenu() {
+    var menu = document.getElementById("acct-menu");
+    if (!menu) return;
+    menu.classList.add("open");
+    document.getElementById("acct-trigger").setAttribute("aria-expanded", "true");
+    fetchAcctToken(); // lazy — one attempt, on first open only
+  }
+
+  // Clipboard helper: async API when available, temporary <textarea> +
+  // execCommand fallback (http remote origins lack the async clipboard API).
+  // Brief "Copied" feedback (label swap for ~1.5 s); total failure alerts.
+  function copyToClipboard(text, btn) {
+    var flash = function () {
+      var orig = btn.dataset.origLabel || (btn.dataset.origLabel = btn.textContent);
+      btn.textContent = "Copied";
+      clearTimeout(btn._copiedTimer);
+      btn._copiedTimer = setTimeout(function () { btn.textContent = orig; }, 1500);
+    };
+    var legacy = function () {
+      try {
+        var ta = document.createElement("textarea");
+        ta.value = text;
+        ta.style.position = "fixed";
+        ta.style.opacity = "0";
+        document.body.appendChild(ta);
+        ta.select();
+        var ok = document.execCommand("copy");
+        document.body.removeChild(ta);
+        return ok;
+      } catch (e) { return false; }
+    };
+    var fallback = function () {
+      if (legacy()) { flash(); return; }
+      alert("Copy failed — select the text and copy it manually.");
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(flash, fallback);
+    } else {
+      fallback();
+    }
+  }
+
+  // Sign-out is CLIENT-SIDE ONLY (#365): there is no server session to
+  // invalidate in the Hicortex server itself — auth is per-request bearer, so
+  // dropping the locally stored tokens IS the sign-out. (The hosted router
+  // separately keeps a Google session cookie and offers /auth/logout — out of
+  // scope here; this only ends the browser's console session.)
+  function signOut() {
+    try {
+      localStorage.removeItem("hicortexToken");
+      localStorage.removeItem("hicortex-dashboard-token");
+    } catch (e) { /* private mode — reload anyway */ }
+    location.reload(); // back to the unauthenticated 401-prompt state
+  }
+
+  function wireAcctMenu() {
+    var trigger = document.getElementById("acct-trigger");
+    if (!trigger) return;
+    trigger.addEventListener("click", function () {
+      var menu = document.getElementById("acct-menu");
+      if (menu && menu.classList.contains("open")) closeAcctMenu();
+      else openAcctMenu();
+    });
+    document.getElementById("acct-reveal").addEventListener("click", function () {
+      acctRevealed = !acctRevealed;
+      renderAcctToken();
+    });
+    var copyToken = document.getElementById("acct-copy-token");
+    copyToken.addEventListener("click", function () {
+      if (acctTokenState === "ok") copyToClipboard(acctConnectLine(), copyToken);
+    });
+    var copyCli = document.getElementById("acct-copy-cli");
+    copyCli.addEventListener("click", function () {
+      if (acctTokenState === "ok") {
+        copyToClipboard("npx @gamaze/hicortex init --server " + location.origin, copyCli);
+      }
+    });
+    var copyMcp = document.getElementById("acct-copy-mcp");
+    copyMcp.addEventListener("click", function () {
+      if (acctTokenState === "ok") copyToClipboard(acctMcpText(), copyMcp);
+    });
+    // Plan & billing lives on the dashboard page — navigate there (append
+    // ?token= when one is known, mirroring the shared-nav link handler) and
+    // land on the digest panel's budget/usage anchor (#371 lands there).
+    document.getElementById("acct-plan").addEventListener("click", function () {
+      var t = null;
+      try {
+        t = token
+          || localStorage.getItem("hicortexToken")
+          || localStorage.getItem("hicortex-dashboard-token");
+      } catch (e) { /* private mode — navigate without a token */ }
+      var u = new URL("/dashboard", location.origin);
+      if (t) u.searchParams.set("token", t);
+      u.hash = "plan-billing";
+      location.href = u.toString();
+    });
+    document.getElementById("acct-signout").addEventListener("click", signOut);
+    renderAcctToken();
+  }
+
+  // Click-outside + Escape close the menu (wired once; the handlers no-op
+  // when the menu isn't rendered).
+  document.addEventListener("click", function (e) {
+    var menu = document.getElementById("acct-menu");
+    if (!menu || !menu.classList.contains("open")) return;
+    var wrap = document.getElementById("nav-account");
+    if (wrap && wrap.contains(e.target)) return;
+    closeAcctMenu();
+  });
+  window.addEventListener("keydown", function (e) {
+    if (e.key === "Escape") closeAcctMenu();
+  });
+
   // =========================================================================
   // DOM references
   // =========================================================================

package/dist/cli.d.ts

@@ -4,6 +4,7 @@
  *
  * Commands:
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
+ *   mcp        Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation

package/dist/cli.js

@@ -5,6 +5,7 @@
  *
  * Commands:
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
+ *   mcp        Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation
@@ -34,6 +35,26 @@ switch (command) {
         });
         break;
     }
+    case "mcp": {
+        // Stdio MCP bridge (#375): speak MCP on stdin/stdout, backed by the
+        // daemon's SSE endpoint (or a remote server via HICORTEX_SERVER_URL).
+        // Registry clients (Claude Desktop, Cursor, the MCP Registry's install
+        // flow) launch stdio commands — this is the command the registry's
+        // server.json declares (`npx -y @gamaze/hicortex mcp`). Starts a local
+        // daemon when the target is loopback and none is running; never spawns
+        // for remote targets. stdout carries ONLY the MCP protocol — all
+        // diagnostics go to stderr (the bridge owns that discipline internally).
+        import("./mcp-stdio.js").then(({ runMcpStdio }) => {
+            runMcpStdio().catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] mcp bridge failed: ${err}`);
+                process.exit(1);
+            });
+        }).catch((err) => {
+            console.error("[hicortex] Failed to load the mcp bridge:", err);
+            process.exit(1);
+        });
+        break;
+    }
     case "init": {
         const serverArg = process.argv.indexOf("--server");
         const serverUrl = serverArg !== -1 ? process.argv[serverArg + 1] : undefined;
@@ -331,6 +352,7 @@ Usage: hicortex <command> [options]
 
 Commands:
   server          Start the MCP HTTP/SSE server (server mode)
+  mcp             Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
   init            Set up Hicortex (server mode, local DB + daemon)
                   Scaffolds 5 editable default memory domains (Work, Personal,
                   People, Health, Finance) in ~/.hicortex/config.json

package/dist/dashboard.d.ts

@@ -351,3 +351,20 @@ export declare function dashboardDataHandler(getDb: () => Database.Database, get
  * 500 with the usual {error} shape (same as dashboardDataHandler).
  */
 export declare function accountHandler(getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;
+/**
+ * Express adapter for GET /account/token — the install's connection token for
+ * the console account menu (#365). SECURITY: echo-only — the caller must
+ * ALREADY present the token (bearer, or the localhost bypass) to receive it,
+ * so this endpoint grants no privilege. It exists so the menu shows the
+ * AUTHORITATIVE server-side token instead of trusting localStorage, which can
+ * be stale after token rotation and is absent entirely for browser sessions
+ * the hosted router authenticates via its session→bearer injection.
+ *
+ * `getToken` receives the boot-resolved PRIMARY token (config authToken ??
+ * HICORTEX_AUTH_TOKEN env) — the value the auth middleware itself accepts as
+ * current, so the menu survives rotation and never echoes the rotation-grace
+ * token. When no token is configured the handler answers 503 (mirrors how the
+ * /auth/* endpoints answer "not configured"); other failures surface as a 500
+ * {error} exactly like accountHandler.
+ */
+export declare function accountTokenHandler(getToken: () => string | undefined): express.RequestHandler;

package/dist/dashboard.js

@@ -26,6 +26,7 @@ exports.backfillSnapshots = backfillSnapshots;
 exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
 exports.accountHandler = accountHandler;
+exports.accountTokenHandler = accountTokenHandler;
 const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
@@ -526,3 +527,34 @@ function accountHandler(getConfig) {
         }
     };
 }
+/**
+ * Express adapter for GET /account/token — the install's connection token for
+ * the console account menu (#365). SECURITY: echo-only — the caller must
+ * ALREADY present the token (bearer, or the localhost bypass) to receive it,
+ * so this endpoint grants no privilege. It exists so the menu shows the
+ * AUTHORITATIVE server-side token instead of trusting localStorage, which can
+ * be stale after token rotation and is absent entirely for browser sessions
+ * the hosted router authenticates via its session→bearer injection.
+ *
+ * `getToken` receives the boot-resolved PRIMARY token (config authToken ??
+ * HICORTEX_AUTH_TOKEN env) — the value the auth middleware itself accepts as
+ * current, so the menu survives rotation and never echoes the rotation-grace
+ * token. When no token is configured the handler answers 503 (mirrors how the
+ * /auth/* endpoints answer "not configured"); other failures surface as a 500
+ * {error} exactly like accountHandler.
+ */
+function accountTokenHandler(getToken) {
+    return (_req, res) => {
+        try {
+            const token = getToken();
+            if (!token) {
+                res.status(503).json({ error: "no auth token configured on this install" });
+                return;
+            }
+            res.status(200).json({ token });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}

package/dist/mcp-server.js

@@ -1599,6 +1599,16 @@ async function startServer(options = {}) {
     // (standard auth middleware, no shell exemption — it carries data); localhost
     // bypass applies. Handler lives in src/dashboard.ts next to its twin.
     app.get("/account", (0, dashboard_js_1.accountHandler)(() => readConfigFile(stateDir)));
+    // GET /account/token — the install's connection token for the console
+    // account menu (#365). Echo-only (see accountTokenHandler's JSDoc): the
+    // caller must already present the token (bearer or localhost bypass), so
+    // this grants no privilege — it exists so the menu shows authoritative
+    // server-side truth instead of a possibly-stale localStorage copy. Passes
+    // the boot-resolved PRIMARY token (the one the auth middleware itself
+    // accepts as current — survives rotation, never echoes the grace token).
+    // Bearer-only like /account: standard auth middleware, no shell exemption
+    // (it carries data); localhost bypass applies.
+    app.get("/account/token", (0, dashboard_js_1.accountTokenHandler)(() => authToken));
     // SSE endpoint — each connection gets its own McpServer + transport
     app.get("/sse", async (req, res) => {
         const transport = new sse_js_1.SSEServerTransport("/messages", res);

package/dist/mcp-stdio.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Hicortex stdio MCP bridge (#375) — the `hicortex mcp` subcommand.
+ *
+ * Registry/stdio MCP clients (Claude Desktop, Cursor, the MCP Registry's own
+ * install flow) launch a stdio command and speak MCP over stdin/stdout. The
+ * daemon's MCP surface is HTTP/SSE on :8787, so this module bridges the two:
+ * a low-level SDK `Server` over `StdioServerTransport` downstream (the client
+ * side) and an SDK `Client` over `SSEClientTransport` upstream (the daemon
+ * side), forwarding tools/list + tools/call. The daemon's MCP surface is
+ * tools-only (no resources/prompts registered in mcp-server.ts) and ping is
+ * auto-answered by the SDK Protocol base, so tools-forwarding loses nothing.
+ *
+ * WHY proxy instead of in-process stdio with direct DB access (design note,
+ * issue #375):
+ *   1. db.ts enables WAL but sets no busy_timeout — a second writer process
+ *      (the common case: the daemon already running on server-mode installs)
+ *      takes immediate SQLITE_BUSY during nightly consolidation's long
+ *      transactions → tool-call failures.
+ *   2. createMcpServer()'s nine tool handlers close over ~10 module-level
+ *      vars initialized by the ~250-line boot inside startServer() —
+ *      in-process would mean refactoring the production boot path or
+ *      duplicating it (drift).
+ *   3. warmEmbedder loads a 150-300 MB ONNX model per process — one per MCP
+ *      client (Claude Desktop + CC + Cursor = 3x), vs zero for the bridge.
+ *   4. mcp-server.ts's own header states the model: "One process, one DB
+ *      connection, one embedder".
+ *
+ * Target resolution (precedence): HICORTEX_SERVER_URL env → remote bridge,
+ * NEVER spawns anything; else config via the SAME semantics as
+ * learnings-identity.resolveConfig() (client-mode serverUrl → remote;
+ * server-mode → http://127.0.0.1:<port ?? 8787>); no usable config →
+ * http://127.0.0.1:8787. Token: HICORTEX_AUTH_TOKEN env → config.authToken.
+ * The token rides SSEClientTransport's requestInit headers (verified in the
+ * installed SDK 1.28: merged into BOTH the GET /sse and POST /messages).
+ *
+ * Local autostart: when the target is loopback and /health is
+ * connection-refused, spawn a DETACHED `cli.js server --port <n>` (unref,
+ * stdio ignored) and poll /health (~250 ms interval, 30 s cap). Concurrent
+ * bridges racing EADDRINUSE self-heal — the loser's child dies, the winner's
+ * daemon answers the poll, so the loop keeps polling regardless of child
+ * state. /health answering but not ok = a foreign or broken service on the
+ * port: explicit error, never a spawn. A remote target that is down is
+ * likewise an explicit error — we never spawn for remote URLs.
+ *
+ * STDIO DISCIPLINE: stdout carries ONLY the MCP protocol. Every diagnostic
+ * goes to stderr; fatal errors are a one-liner on stderr + non-zero exit
+ * (thrown to cli.ts's catch). Cancellation downstream→upstream rides the
+ * SDK-native path: the Protocol base aborts the handler's extra.signal on
+ * notifications/cancelled, and passing that signal into client.callTool makes
+ * the upstream Client emit its own notifications/cancelled with the CORRECT
+ * upstream request id (a verbatim forward would carry the downstream id,
+ * which means nothing to the daemon) — and reject the in-flight bridge call.
+ */
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/** Where the bridge target came from — surfaces in the startup diagnostic. */
+export type BridgeTargetSource = "option" | "env" | "config" | "default";
+export interface BridgeTarget {
+    /** Base URL, trailing slashes stripped (endpoints append /sse, /health). */
+    url: string;
+    /** Loopback target → eligible for local autostart. */
+    local: boolean;
+    /** Port of the resolved URL — what an autospawned daemon must listen on. */
+    port: number;
+    source: BridgeTargetSource;
+}
+/** Loopback check for URL hostnames (Node's URL keeps the brackets on [::1]). */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Resolve the daemon/server the bridge should talk to. Precedence: explicit
+ * option (the runMcpStdio test seam) → HICORTEX_SERVER_URL env → config file
+ * (client-mode serverUrl = remote; server-mode = localhost, the
+ * resolveConfig() semantics already shared by both CC hooks) → default local
+ * 8787. Blank/whitespace env values are ignored, not mistaken for targets.
+ */
+export declare function resolveBridgeTarget(explicitUrl?: string): BridgeTarget;
+/**
+ * Resolve the bearer token for the upstream connection: explicit option →
+ * HICORTEX_AUTH_TOKEN env → config.authToken. Undefined = no token (a local
+ * daemon needs none — loopback bypasses auth).
+ */
+export declare function resolveBridgeToken(explicitToken?: string): string | undefined;
+export interface HealthProbe {
+    /** Any HTTP response arrived (even a non-200 one). */
+    reachable: boolean;
+    /** The endpoint answered ok — a healthy Hicortex /health. */
+    ok: boolean;
+}
+/**
+ * One GET /health probe. Connection refused / timeout / DNS failure →
+ * { reachable: false }; a response that is not ok → { reachable: true, ok:
+ * false } — the two carry different autostart decisions, so a boolean alone
+ * cannot express them.
+ */
+export declare function probeHealthOnce(url: string, timeoutMs?: number): Promise<HealthProbe>;
+export type AutostartDecision = {
+    action: "bridge";
+} | {
+    action: "spawn";
+} | {
+    action: "fail";
+    reason: string;
+};
+/**
+ * Pure decision from one health probe: healthy → bridge; refused + loopback
+ * → spawn a local daemon; refused + remote → fail with an actionable message
+ * (never spawn for remote URLs); answering-but-not-ok → fail explicitly (a
+ * foreign or broken service owns the port — spawning next to it cannot help).
+ */
+export declare function decideAutostart(probe: HealthProbe, target: BridgeTarget): AutostartDecision;
+export interface EnsureDaemonOptions {
+    /** Local autostart toggle (default true). Remote targets never spawn. */
+    autostart?: boolean;
+    probeHealth?: (url: string) => Promise<HealthProbe>;
+    spawnDaemon?: (port: number) => Promise<void> | void;
+    /** Poll pacing overrides — small values keep the timeout test fast. */
+    pollIntervalMs?: number;
+    pollTotalMs?: number;
+}
+/**
+ * Ensure something healthy answers at the target before bridging: probe once,
+ * decide, and if spawning — poll until healthy (or the deadline). Throws on
+ * every fail-path (explicit error, never silent degradation).
+ */
+export declare function ensureDaemonReady(target: BridgeTarget, options?: EnsureDaemonOptions): Promise<void>;
+export interface McpStdioOptions extends EnsureDaemonOptions {
+    /** Explicit target URL (test seam; normally resolved from env/config). */
+    serverUrl?: string;
+    /** Explicit bearer token (test seam; normally env → config). */
+    authToken?: string;
+    /** Injectable downstream transport (test seam; default: real stdio). */
+    downstream?: Transport;
+}
+/**
+ * Run the stdio MCP bridge. Resolves only after the downstream transport
+ * closes (the lifecycle handlers then exit the process); every setup failure
+ * throws for cli.ts to report on stderr and exit 1.
+ */
+export declare function runMcpStdio(options?: McpStdioOptions): Promise<void>;