@deepsql/mcp 0.20.0 → 0.22.0

package/README.md

@@ -53,9 +53,14 @@ DBA persona, read-only-by-default tool scoping, and DeepSQL skins.
 - **No LLM key needed** — the DeepSQL backend proxies the model
   (`/api/llm/v1`), authenticated by your `deepsql login` token. The agent
   never sees a provider key.
-- **First run** installs the agent runtime (Python via the Hermes
-  installer + Node for the TUI) and provisions a local `deepsql` profile.
-  Subsequent launches are instant.
+- **Runtime install** — by default `npm install -g @deepsql/mcp` pre-installs
+  the agent runtime (a Hermes build pinned to a known-good commit) so the first
+  `deepsql` is instant. It's best-effort and never fails the npm install, and
+  skips automatically in CI and non-global installs. Opt out with
+  `DEEPSQL_SKIP_AGENT_SETUP=1` — pure-MCP users (Claude Code / Cursor) then
+  don't pull the runtime, and it installs lazily on first `deepsql agent`
+  instead. The per-user `deepsql` profile is provisioned on first launch after
+  login (it needs your token).
 - **Read-only by default** — only the DeepSQL tools, memory, and skills are
   enabled; host-affecting toolsets (terminal/file/code-exec/browser) are
   disabled. `apply_index_recommendation` stays server-side confirm-gated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
@@ -14,6 +14,7 @@
     "bin",
     "skills",
     "src",
+    "scripts",
     "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
@@ -21,7 +22,8 @@
     "codex_config.customer.example.toml"
   ],
   "scripts": {
-    "test": "node --test deepsql-phase1-lib.test.js src/*.test.js src/**/*.test.js"
+    "test": "node --test deepsql-phase1-lib.test.js src/*.test.js src/**/*.test.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "engines": {
     "node": ">=20"

package/scripts/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+
+// Postinstall: intentionally a no-op heavy-wise.
+//
+// The DeepSQL Agent is now a THIN client — `deepsql` / `deepsql agent` talk to
+// the server-side agent over the backend's brokered /agent/chat endpoint, so
+// there is NO local agent runtime to download. `npm install -g @deepsql/mcp` is
+// fast and quiet; nothing to pre-build.
+//
+// We only print a short next-steps hint on a global install (and stay silent for
+// CI / local dependency installs so we never clutter other projects' logs).
+
+try {
+  if (process.env.CI) process.exit(0);
+  const isGlobal = String(process.env.npm_config_global || "") === "true";
+  if (!isGlobal) process.exit(0);
+
+  process.stdout.write(
+    "\nDeepSQL installed. Next:\n" +
+    "  deepsql login --url <your-deepsql-url>\n" +
+    "  deepsql                      # chat with the DeepSQL Agent (connects to your server)\n\n"
+  );
+} catch {
+  // Never let a cosmetic hint fail the install.
+}
+process.exit(0);

package/src/agent/bootstrap.js

@@ -7,6 +7,7 @@
 // config rewrite keeps the token/connection fresh.
 
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 const { userHome } = require("../user-home");
@@ -17,15 +18,65 @@ const AGENT_DIR = path.join(HERMES_HOME, "hermes-agent");
 const PROFILE = "deepsql";
 const PROFILE_HOME = path.join(HERMES_HOME, "profiles", PROFILE);
 
+const INSTALL_URL = "https://hermes-agent.nousresearch.com/install.sh";
+// Pin the Hermes runtime to the exact commit our bundled TUI (agent-profile/
+// tui/entry.js, HERMES_VERSION 0.17.0) was built against. This makes installs
+// reproducible AND guarantees the branded-TUI overlay's version guard matches,
+// so end users get the DeepSQL wordmark/welcome — not a "latest main" build
+// that drifts in behavior and skips our overlay. Bump alongside the bundle.
+const HERMES_COMMIT = "92d40c2553961243991376bf889d833e8326caf7";
+
+// Extra dirs the Hermes runtime + its installer rely on but a bare GUI/login
+// shell PATH (as seen by a spawned Node process) often lacks: the venv, the
+// installer's `hermes` symlink targets, and Homebrew (uv/node/git).
+function extraPathDirs() {
+  return [
+    path.join(AGENT_DIR, ".venv", "bin"),
+    path.join(HOME, ".local", "bin"),
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    "/usr/local/lib/hermes-agent/.venv/bin",
+  ];
+}
+
+// Env for any spawn that runs (or installs) Hermes: augmented PATH so node/uv/
+// git resolve, UV_NO_CONFIG so uv ignores stray project configs, and a pinned
+// HERMES_HOME so the install/profile lands where we expect.
+function hermesEnv(extra = {}) {
+  const sep = path.delimiter;
+  const have = (process.env.PATH || "").split(sep);
+  const merged = [...extraPathDirs().filter((d) => !have.includes(d)), ...have].join(sep);
+  return { ...process.env, PATH: merged, UV_NO_CONFIG: "1", HERMES_HOME, ...extra };
+}
+
+// All the places the official installer may drop a runnable `hermes` for a
+// non-root install (venv) or an FHS/root install (/usr/local), plus the PATH.
+function findHermes() {
+  const candidates = [];
+  if (process.env.HERMES_INSTALL_DIR) {
+    candidates.push(path.join(process.env.HERMES_INSTALL_DIR, ".venv", "bin", "hermes"));
+  }
+  candidates.push(
+    path.join(AGENT_DIR, ".venv", "bin", "hermes"),
+    "/usr/local/lib/hermes-agent/.venv/bin/hermes",
+    path.join(HOME, ".local", "bin", "hermes"),
+    "/usr/local/bin/hermes"
+  );
+  for (const bin of candidates) {
+    if (!fs.existsSync(bin)) continue;
+    if (spawnSync(bin, ["--version"], { stdio: "ignore", env: hermesEnv() }).status === 0) return bin;
+  }
+  // Last resort: a `hermes` already on the (augmented) PATH.
+  if (spawnSync("hermes", ["--version"], { stdio: "ignore", env: hermesEnv() }).status === 0) return "hermes";
+  return null;
+}
+
 function hermesBin() {
-  const venv = path.join(AGENT_DIR, ".venv", "bin", "hermes");
-  return fs.existsSync(venv) ? venv : "hermes";
+  return findHermes() || path.join(AGENT_DIR, ".venv", "bin", "hermes");
 }
 
 function hermesInstalled() {
-  if (fs.existsSync(path.join(AGENT_DIR, ".venv", "bin", "hermes"))) return true;
-  const r = spawnSync("hermes", ["--version"], { stdio: "ignore" });
-  return r.status === 0;
+  return findHermes() !== null;
 }
 
 function mcpServerPath() {
@@ -42,16 +93,39 @@ function distSource() {
   return null;
 }
 
-function ensureHermes(io) {
+// Install the Hermes runtime, pinned + non-interactive, with the output teed to
+// a log so a failure surfaces a real cause instead of a vague "can't set up".
+// `quiet` (postinstall) hides the live stream; interactive first-run shows it.
+function ensureHermes(io, { quiet = false } = {}) {
   const err = (io && io.stderr) || process.stderr;
   if (hermesInstalled()) return true;
-  err.write("DeepSQL Agent needs its runtime (first run) — installing, this may take a minute…\n");
-  const r = spawnSync(
-    "bash",
-    ["-lc", "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup"],
-    { stdio: "inherit" }
+
+  err.write("DeepSQL Agent: installing the agent runtime (first run; ~1–2 min)…\n");
+  const logFile = path.join(os.tmpdir(), `deepsql-agent-install-${process.pid}.log`);
+  // --commit pins the checkout; --skip-setup/--non-interactive avoid the
+  // wizard + any TTY prompt. tee keeps a persisted log for diagnostics.
+  const script =
+    `curl -fsSL ${INSTALL_URL} | bash -s -- ` +
+    `--skip-setup --non-interactive --commit ${HERMES_COMMIT} 2>&1 | tee ${JSON.stringify(logFile)}`;
+  const r = spawnSync("bash", ["-lc", script], {
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit",
+    env: hermesEnv(),
+  });
+
+  if (hermesInstalled()) {
+    err.write(quiet
+      ? "✓ DeepSQL Agent runtime installed.\n"
+      : "✓ DeepSQL Agent runtime installed. (Ignore any \"run hermes setup\" note above — DeepSQL configures it for you.)\n");
+    return true;
+  }
+  err.write(
+    "DeepSQL Agent: the runtime install did not complete.\n" +
+      `  Install log: ${logFile}\n` +
+      `  Exit code:   ${r.status == null ? "n/a" : r.status}\n` +
+      "  You can retry, or install Hermes manually: " +
+      `curl -fsSL ${INSTALL_URL} | bash -s -- --commit ${HERMES_COMMIT}\n`
   );
-  return r.status === 0 && hermesInstalled();
+  return false;
 }
 
 function q(s) {
@@ -92,16 +166,39 @@ display:
 `;
   fs.writeFileSync(path.join(PROFILE_HOME, "config.yaml"), config);
 
+  // OPENAI_BASE_URL/OPENAI_API_KEY are belt-and-suspenders: Hermes' first-run
+  // guard (_has_any_provider_configured) treats either as "a provider is
+  // configured", so the "run hermes setup" gate can never fire on a fresh
+  // machine even if config-load timing differs. They point at the SAME backend
+  // proxy as the model block, authed by the user's DeepSQL token.
   const env =
 `DEEPSQL_API_BASE_URL=${apiBase}
 DEEPSQL_AUTH_TOKEN=${token}
 DEEPSQL_MCP_SERVER=${mcp}
 DEEPSQL_DEFAULT_CONNECTION_ID=${conn}
+OPENAI_BASE_URL=${proxy}
+OPENAI_API_KEY=${token}
 HERMES_REVISION=deepsql-cli
 `;
   fs.writeFileSync(path.join(PROFILE_HOME, ".env"), env, { mode: 0o600 });
 }
 
+// Env for spawning the TUI: augmented PATH (so the TUI's node + the MCP
+// server's node resolve), the provider vars that defeat Hermes' first-run
+// guard regardless of config state, and HERMES_TUI_DIR pointing at our prebuilt
+// branded TUI (when the Hermes version matches) so Hermes runs it directly with
+// no esbuild — branded on the first launch.
+function launchEnv(session) {
+  const base = session.baseUrl.replace(/\/?$/, "/");
+  const extra = {
+    OPENAI_BASE_URL: base + "api/llm/v1",
+    OPENAI_API_KEY: session.token,
+  };
+  const tui = brandedTuiDir();
+  if (tui) extra.HERMES_TUI_DIR = tui;
+  return hermesEnv(extra);
+}
+
 function installProfileAssets(io) {
   const err = (io && io.stderr) || process.stderr;
   const src = distSource();
@@ -110,8 +207,19 @@ function installProfileAssets(io) {
     return false;
   }
   const bin = hermesBin();
-  const baseEnv = { ...process.env, UV_NO_CONFIG: "1" };
-  spawnSync(bin, ["profile", "install", src, "--name", PROFILE, "--force", "--yes"], { stdio: "ignore", env: baseEnv });
+  const baseEnv = hermesEnv();
+  const inst = spawnSync(
+    bin,
+    ["profile", "install", src, "--name", PROFILE, "--force", "--yes"],
+    { encoding: "utf8", env: baseEnv }
+  );
+  if (inst.status !== 0) {
+    err.write(
+      "DeepSQL Agent: provisioning the profile failed.\n" +
+        `  ${(inst.stderr || inst.stdout || "(no output)").trim().split("\n").slice(-6).join("\n  ")}\n`
+    );
+    return false;
+  }
   // Skin loads from <profile>/skins/.
   const skin = path.join(src, "skins", "deepsql.yaml");
   if (fs.existsSync(skin)) {
@@ -119,12 +227,13 @@ function installProfileAssets(io) {
     fs.mkdirSync(dst, { recursive: true });
     fs.copyFileSync(skin, path.join(dst, "deepsql.yaml"));
   }
-  // Read-only sandbox: only deepsql + skills/memory remain.
+  // Read-only sandbox: only deepsql + skills/memory remain. Non-fatal — the
+  // shipped distribution already scopes tools; this is defense in depth.
   spawnSync(
     bin,
     ["tools", "disable", "terminal", "file", "code_execution", "browser", "computer_use",
      "image_gen", "tts", "vision", "web", "delegation", "cronjob"],
-    { stdio: "ignore", env: { ...baseEnv, HERMES_HOME: PROFILE_HOME } }
+    { stdio: "ignore", env: hermesEnv({ HERMES_HOME: PROFILE_HOME }) }
   );
   return fs.existsSync(PROFILE_HOME);
 }
@@ -138,8 +247,7 @@ function ensureProfile(session, io) {
 }
 
 // Installed Hermes version (parsed from the runtime's __init__.py). Null if the
-// runtime layout isn't what we expect (e.g. PATH-only install) — overlay is then
-// skipped and the user gets the stock TUI with our skin.
+// runtime layout isn't what we expect (e.g. PATH-only install).
 function installedHermesVersion() {
   try {
     const init = path.join(AGENT_DIR, "hermes_cli", "__init__.py");
@@ -150,56 +258,38 @@ function installedHermesVersion() {
   }
 }
 
-// Overlay the prebuilt, DeepSQL-branded TUI bundle (custom DEEPSQL wordmark,
-// "What I can do" welcome panel, DBA placeholders) onto the installed Hermes
-// runtime's `ui-tui/dist/entry.js`. This delivers the full branded experience
-// with NO build step on the user's machine.
+// The DeepSQL-branded prebuilt TUI bundle shipped in the package, as a directory
+// laid out the way Hermes' `HERMES_TUI_DIR` mechanism expects: `<dir>/dist/entry.js`.
+// When that env var points here, Hermes runs our entry.js DIRECTLY — no npm
+// install, no esbuild — so the custom DEEPSQL wordmark / welcome panel / DBA
+// placeholders show on the very FIRST launch. (The earlier copy-into-the-clone
+// approach lost every launch because Hermes "always esbuild"s the normal path.)
 //
-// Guarded by the Hermes version our bundle was built against: a prebuilt
-// entry.js speaks the TUI↔CLI protocol of one Hermes release, so we overlay
-// only on an exact version match. On any mismatch (or a missing bundle) we
-// leave the stock TUI in place — it still renders our skin (DeepSQL name +
-// maroon palette via skins/deepsql.yaml), just without the custom wordmark.
-//
-// We refresh the overlay on every launch and bump its mtime past the TUI build
-// inputs so Hermes' freshness check (`_tui_need_rebuild`, an mtime compare of
-// dist/entry.js vs src/) never rebuilds over it after a `hermes update`.
-function ensureBrandedTui(io) {
-  const err = (io && io.stderr) || process.stderr;
+// Guarded by the Hermes version our bundle was built against: a prebuilt entry.js
+// speaks one release's TUI↔CLI protocol, so we only point at it on an exact
+// version match (the runtime is pinned to HERMES_COMMIT, so it matches on our
+// installs). On any mismatch / missing bundle we return null and let Hermes use
+// its own (stock) TUI, which still renders our skin (DeepSQL name + maroon).
+function brandedTuiDir() {
   try {
     const tuiDir = path.resolve(__dirname, "..", "..", "agent-profile", "tui");
-    const bundledEntry = path.join(tuiDir, "entry.js");
-    if (!fs.existsSync(bundledEntry)) return false; // skin-only branding
-    const builtFor = (() => {
-      try { return fs.readFileSync(path.join(tuiDir, "HERMES_VERSION"), "utf8").trim(); }
-      catch { return null; }
-    })();
+    if (!fs.existsSync(path.join(tuiDir, "dist", "entry.js"))) return null;
+    const builtFor = fs.readFileSync(path.join(tuiDir, "HERMES_VERSION"), "utf8").trim();
     const installed = installedHermesVersion();
-    if (!builtFor || !installed || builtFor !== installed) return false; // degrade to stock TUI + skin
-
-    const distDir = path.join(AGENT_DIR, "ui-tui", "dist");
-    const target = path.join(distDir, "entry.js");
-    fs.mkdirSync(distDir, { recursive: true });
-    const same =
-      fs.existsSync(target) && fs.statSync(target).size === fs.statSync(bundledEntry).size;
-    if (!same) fs.copyFileSync(bundledEntry, target);
-    // Bump mtime past every TUI build input so the freshness check never
-    // rebuilds the stock TUI over our branded bundle.
-    const future = new Date(Date.now() + 60_000);
-    fs.utimesSync(target, future, future);
-    return true;
-  } catch (e) {
-    err.write(`DeepSQL Agent: branded TUI overlay skipped (${e.message}); using stock TUI.\n`);
-    return false;
+    if (!builtFor || !installed || builtFor !== installed) return null;
+    return tuiDir;
+  } catch {
+    return null;
   }
 }
 
 module.exports = {
   ensureHermes,
   ensureProfile,
-  ensureBrandedTui,
+  brandedTuiDir,
   hermesBin,
   hermesInstalled,
+  launchEnv,
   PROFILE,
   PROFILE_HOME,
 };

package/src/cli.js

@@ -90,13 +90,13 @@ const GLOBAL_OPTIONS = [
 
 const COMMAND_HELP = {
   agent: {
-    description: "Launch the DeepSQL Agent — an interactive chat TUI for DBA work, BI questions, and database guardrails. Running `deepsql` with no command in a terminal launches it too.",
-    usage: "deepsql agent [options]   (or just: deepsql)",
+    description: "Chat with the DeepSQL Agent — DBA work, BI questions, and database guardrails. A thin client: it connects to your server's agent (the same one behind the web Agent tab and Slack), nothing installs locally. Bare `deepsql` in a terminal opens interactive chat; pass a question for a one-shot.",
+    usage: 'deepsql agent ["<question>"] [options]   (or just: deepsql)',
     options: [
       ["--url <url>",          "DeepSQL instance to use (default: saved login)"],
-      ["--connection <name>",  "Default connection for the session"],
+      ["--connection <name>",  "Connection to ground answers on (default: saved active connection)"],
     ],
-    notes: "First run installs the agent runtime. Uses your saved `deepsql login` — no LLM key needed (the backend proxies the model).",
+    notes: "No local runtime or LLM key needed — the server runs the agent and proxies the model. Interactive chat resumes your most recent conversation (shared with the web Agent tab).",
   },
 
   login: {

package/src/commands/agent.js

@@ -1,15 +1,44 @@
 "use strict";
 
-// `deepsql agent` (and bare `deepsql` in a terminal): launch the DeepSQL Agent —
-// a branded Hermes TUI for DBA / BI / database-guard chat. Resolves the saved
-// login, lazily installs the runtime, provisions the `deepsql` profile pointed
-// at the backend LLM proxy (no LLM key needed), then hands the terminal to the TUI.
+// `deepsql agent` (and bare `deepsql` in a terminal): the DeepSQL Agent, as a
+// THIN client. It does not run an agent runtime locally — it talks to the
+// server-side agent through the backend's brokered, authenticated
+// `/agent/chat` endpoint (the same agent that powers the web Agent tab and
+// Slack). Identity, profile, connection scope, and conversation history are all
+// resolved server-side from your saved `deepsql login` — nothing heavy installs,
+// and your terminal shares the same conversations as the web app.
+//
+//   deepsql agent "how many active hotels?"   one-shot
+//   deepsql                                    interactive chat (resumes latest)
 
-const { spawn } = require("node:child_process");
+const readline = require("node:readline");
+const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
-const { ensureHermes, ensureProfile, ensureBrandedTui, hermesBin, PROFILE } = require("../agent/bootstrap");
+const { resolveConnectionId } = require("./_connections");
+
+// The brokered turn can run a full multi-tool agent loop server-side; allow well
+// past the backend's own per-turn ceiling so we don't abandon a valid answer.
+const TURN_TIMEOUT_MS = 320000;
+
+async function runTurn(session, connectionId, message, conversationId) {
+  return request(session.baseUrl, "/agent/chat", {
+    method: "POST",
+    token: session.token,
+    json: { message, connectionId, conversationId },
+    timeoutMs: TURN_TIMEOUT_MS,
+  });
+}
+
+function renderReply(stdout, resp) {
+  if (resp && resp.ok && resp.answer && String(resp.answer).trim()) {
+    stdout.write(`\n${String(resp.answer).trim()}\n`);
+  } else {
+    stdout.write(`\n⚠ ${(resp && resp.error) || "the agent run ended early"}\n`);
+  }
+}
 
 async function run(opts, io = {}) {
+  const stdout = io.stdout || process.stdout;
   const stderr = io.stderr || process.stderr;
 
   let session;
@@ -20,23 +49,69 @@ async function run(opts, io = {}) {
     return 1;
   }
 
-  if (!ensureHermes(io)) {
-    stderr.write("Could not set up the DeepSQL Agent runtime. See https://github.com/NousResearch/hermes-agent for manual install.\n");
-    return 1;
+  // Connection is optional — the agent can chat without one and will ask if a
+  // question needs a database. Resolve the active default when present.
+  let connectionId = null;
+  try {
+    connectionId = await resolveConnectionId(session, opts.connection);
+  } catch {
+    /* no default connection set — fine */
   }
-  if (!ensureProfile(session, io)) {
-    stderr.write("Could not provision the DeepSQL Agent profile.\n");
-    return 1;
+
+  const message = (opts.positional || []).join(" ").trim();
+
+  // One-shot: a question on the command line.
+  if (message) {
+    try {
+      const resp = await runTurn(session, connectionId, message, null);
+      renderReply(stdout, resp);
+      return resp && resp.ok ? 0 : 1;
+    } catch (e) {
+      stderr.write(`Agent request failed: ${e.message}\n`);
+      return 1;
+    }
   }
-  ensureBrandedTui(io); // best-effort: full branded TUI when versions match, else stock TUI + skin
 
-  // Hand the terminal to the branded TUI (profile config sets interface=tui).
-  const child = spawn(hermesBin(), ["-p", PROFILE, "--tui"], { stdio: "inherit", env: process.env });
+  // Interactive: a line REPL against the server agent. Requires a TTY.
+  if (!stdout.isTTY) {
+    stderr.write('Usage: deepsql agent "<question>"   (or run in a terminal for interactive chat)\n');
+    return 2;
+  }
+
+  stdout.write("DeepSQL Agent — connected to your server agent. Type a question; `exit` or Ctrl-C to quit.\n");
+  // conversationId stays null on the first turn so the server resumes your most
+  // recent conversation for this connection (shared with the web Agent tab);
+  // subsequent turns reuse the id it returns.
+  let conversationId = null;
+  const rl = readline.createInterface({ input: process.stdin, output: stdout, prompt: "\nyou › " });
+  rl.prompt();
+
   return await new Promise((resolve) => {
-    child.on("exit", (code) => resolve(code ?? 0));
-    child.on("error", (err) => {
-      stderr.write(`Failed to launch the DeepSQL Agent: ${err.message}\n`);
-      resolve(1);
+    rl.on("line", async (line) => {
+      const text = line.trim();
+      if (!text) {
+        rl.prompt();
+        return;
+      }
+      if (text === "exit" || text === "quit") {
+        rl.close();
+        return;
+      }
+      rl.pause();
+      stdout.write("…thinking\n");
+      try {
+        const resp = await runTurn(session, connectionId, text, conversationId);
+        if (resp && resp.conversationId) conversationId = resp.conversationId;
+        renderReply(stdout, resp);
+      } catch (e) {
+        stdout.write(`\n⚠ ${e.message}\n`);
+      }
+      rl.resume();
+      rl.prompt();
+    });
+    rl.on("close", () => {
+      stdout.write("\nBye.\n");
+      resolve(0);
     });
   });
 }