@deepsql/mcp 0.19.0 → 0.21.0

package/deepsql-phase1-lib.js

@@ -350,9 +350,11 @@ const TOOL_DEFINITIONS = [
   {
     name: "optimize_slow_query",
     description:
-      "Get AI-generated optimization recommendations for a specific slow query — including "
-      + "index suggestions, query rewrites, and expected performance impact. DeepSQL inspects "
-      + "the query against the connection's schema, existing indexes, and workload patterns. "
+      "Get an AI query REWRITE and plan diagnosis for one specific slow query. "
+      + "Single-query scoped: returns a rewritten SQL (validated against the live DB), "
+      + "the plan bottleneck, and an estimated improvement. Does NOT recommend indexes — "
+      + "index and pre-aggregation recommendations require the whole workload and come "
+      + "from the holistic Workload Analysis (and the get_index_recommendations tool). "
       + "Pass `avgExecutionTimeMs` to anchor the impact estimate to a real baseline.",
     inputSchema: {
       type: "object",
@@ -1570,7 +1572,11 @@ function buildToolResult(name, payload, extra = {}) {
         text: summary,
       },
     ],
-    structuredContent: payload,
+    // MCP spec requires `structuredContent` to be a JSON object. Several tools
+    // (list_connections, get_relationships, list_business_rules, …) return a
+    // top-level array from the backend; wrap those so spec-strict clients
+    // (e.g. the `mcp` Python SDK used by Hermes) don't reject the result.
+    structuredContent: Array.isArray(payload) ? { items: payload } : payload,
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.19.0",
-  "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
+  "version": "0.21.0",
+  "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
     "deepsql-mcp": "deepsql-phase1-server.js"
@@ -14,13 +14,16 @@
     "bin",
     "skills",
     "src",
+    "scripts",
+    "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
     "claude_desktop_config.customer.example.json",
     "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,57 @@
+#!/usr/bin/env node
+"use strict";
+
+// Postinstall: pre-install the DeepSQL Agent (Hermes) runtime at `npm install -g`
+// time so the first `deepsql` launch is instant instead of triggering a heavy
+// one-time download. Best-effort and NON-FATAL — it never fails the npm install.
+//
+// Opt out (e.g. pure-MCP users who only want the editor tools, not the agent):
+//   DEEPSQL_SKIP_AGENT_SETUP=1 npm install -g @deepsql/mcp
+//
+// It auto-skips when there's nothing/no-one to set up for:
+//   - CI environments (process.env.CI)
+//   - non-global installs (local dev `npm install`, dependency installs)
+// The profile itself is provisioned later, on first `deepsql` after login,
+// because it needs the user's token.
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function skip(reason) {
+  // Silent for the common "not global / CI" cases; only note an explicit opt-out.
+  if (reason) log(`DeepSQL Agent: ${reason}`);
+  process.exit(0);
+}
+
+try {
+  if (process.env.DEEPSQL_SKIP_AGENT_SETUP) {
+    skip("agent runtime setup skipped (DEEPSQL_SKIP_AGENT_SETUP set).");
+  }
+  if (process.env.CI) skip();
+  // Only pre-install on an explicit global install (or a forced run). Local /
+  // dependency installs shouldn't pull a Python+Node runtime.
+  const isGlobal = String(process.env.npm_config_global || "") === "true";
+  if (!isGlobal && !process.env.DEEPSQL_FORCE_AGENT_SETUP) skip();
+
+  const { ensureHermes, hermesInstalled } = require("../src/agent/bootstrap");
+
+  if (hermesInstalled()) {
+    log("✓ DeepSQL Agent runtime already present.");
+    process.exit(0);
+  }
+
+  log("DeepSQL Agent: pre-installing the agent runtime so `deepsql` starts instantly.");
+  log("  (Opt out next time with DEEPSQL_SKIP_AGENT_SETUP=1.)");
+  const ok = ensureHermes({ stderr: process.stdout });
+  if (ok) {
+    log("✓ DeepSQL Agent runtime ready. Run `deepsql login`, then `deepsql`.");
+  } else {
+    // Non-fatal: the lazy installer will retry on first `deepsql agent`.
+    log("DeepSQL Agent: runtime not pre-installed; it'll be set up on first `deepsql` run.");
+  }
+} catch (e) {
+  // Never break the npm install over agent pre-setup.
+  log(`DeepSQL Agent: skipped runtime pre-install (${e && e.message ? e.message : e}).`);
+}
+process.exit(0);

package/skills/SKILL_BODY.md

@@ -98,7 +98,7 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_slow_query_customers(connectionId)` | Tenants ranked by total slow-query time — answers "which customer is driving the load?" |
 | `get_query_samples(connectionId, fingerprint)` | Literal SQL samples with bind values for a fingerprint, slowest-first. Use to reproduce an execution or run a real EXPLAIN. |
 | `get_slow_query_insights(connectionId, kind?, window?, limit?)` | Pre-computed AI insights — `hotspots`, `remediation`, `tail-risk`, `plan-drift`, `skew`, or `all` (default). |
-| `optimize_slow_query(connectionId, queryText, avgExecutionTimeMs?)` | AI optimization recommendations for a specific SQL — index suggestions, query rewrites, estimated impact. |
+| `optimize_slow_query(connectionId, queryText, avgExecutionTimeMs?)` | AI query REWRITE + plan diagnosis for one SQL (single-query scoped). NOT indexes — those need the whole workload; use `get_index_recommendations` or Workload Analysis. |
 | `get_table_growth(connectionId, tableName?, days?)` | Persistent stats history: per-table size/row time series + headline rollups. Use to answer "which tables are growing fastest?" or "how much has X grown in the last month?" without scanning the live DB. |
 | `get_growth_anomalies(connectionId, tableName?, unacknowledgedOnly?, days?)` | DeepSQL-flagged sudden growth spikes with severity (CRITICAL/WARNING/INFO), anomaly type, before/after sizes, confidence score. Check this BEFORE walking the user through a slow-query plan — a recent growth anomaly is often the real root cause. |
 | `execute_sql(connectionId, query, ...)` | Run any SQL — SELECT for everyone, DML/DDL for admins (two-step confirm). |
@@ -138,10 +138,11 @@ called by claude-code via deepsql CLI").
 deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 ```
 
-### Command catalog (19 top-level commands)
+### Command catalog (20 top-level commands)
 
 | Command | What it does | MCP equivalent? |
 |---|---|---|
+| `deepsql agent` (or bare `deepsql` in a terminal) | Launch the **DeepSQL Agent** — an interactive DBA/BI chat TUI. Uses your saved `deepsql login`; the model is proxied by the DeepSQL backend, so no LLM key is needed. First run installs the agent runtime. | none — interactive TUI |
 | `deepsql login` | Authorize CLI against a DeepSQL host (browser PKCE / device code / password) | none — interactive only |
 | `deepsql logout` | Revoke the saved token | none |
 | `deepsql whoami` | Show the logged-in user, role, URL, pinned connection | none |

package/src/agent/bootstrap.js

@@ -0,0 +1,293 @@
+"use strict";
+
+// Lazy bootstrap for the DeepSQL Agent (Hermes-based TUI): detect/install the
+// Hermes runtime and provision the `deepsql` profile (model → the backend LLM
+// proxy with the user's token; DeepSQL MCP tools; DBA persona/skills; subtle
+// DeepSQL skin; read-only sandbox). Provisioning is idempotent; the per-launch
+// 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");
+
+const HOME = userHome();
+const HERMES_HOME = path.join(HOME, ".hermes");
+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() {
+  return findHermes() || path.join(AGENT_DIR, ".venv", "bin", "hermes");
+}
+
+function hermesInstalled() {
+  return findHermes() !== null;
+}
+
+function mcpServerPath() {
+  return path.resolve(__dirname, "..", "..", "deepsql-phase1-server.js");
+}
+
+// Profile distribution (SOUL.md + skills/ + skins/): the bundled copy shipped in
+// the package, else the repo `hermes/` dir during local development.
+function distSource() {
+  const bundled = path.resolve(__dirname, "..", "..", "agent-profile");
+  if (fs.existsSync(path.join(bundled, "distribution.yaml"))) return bundled;
+  const repoHermes = path.resolve(__dirname, "..", "..", "..", "hermes");
+  if (fs.existsSync(path.join(repoHermes, "distribution.yaml"))) return repoHermes;
+  return null;
+}
+
+// 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: 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("✓ 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 false;
+}
+
+function q(s) {
+  return `"${String(s).replace(/"/g, '\\"')}"`;
+}
+
+function writeRuntimeConfig(session) {
+  fs.mkdirSync(PROFILE_HOME, { recursive: true });
+  const base = session.baseUrl.replace(/\/?$/, "/"); // ensure single trailing /
+  const proxy = base + "api/llm/v1";
+  const apiBase = base + "api/";
+  const token = session.token;
+  const mcp = mcpServerPath();
+  const conn = session.defaultConnection || "";
+
+  const config =
+`model:
+  default: gpt-5.4
+  provider: custom
+  base_url: ${q(proxy)}
+  api_key: ${q(token)}
+  api_mode: chat_completions
+  context_length: 272000
+mcp_servers:
+  deepsql:
+    command: node
+    args:
+      - ${q(mcp)}
+    env:
+      DEEPSQL_API_BASE_URL: ${q(apiBase)}
+      DEEPSQL_MCP_USER_ID: deepsql-cli
+      DEEPSQL_AUTH_TOKEN: ${q(token)}
+approvals:
+  mode: smart
+display:
+  skin: deepsql
+  interface: tui
+`;
+  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();
+  if (!src) {
+    err.write("DeepSQL agent profile assets not found in this install.\n");
+    return false;
+  }
+  const bin = hermesBin();
+  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)) {
+    const dst = path.join(PROFILE_HOME, "skins");
+    fs.mkdirSync(dst, { recursive: true });
+    fs.copyFileSync(skin, path.join(dst, "deepsql.yaml"));
+  }
+  // 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: hermesEnv({ HERMES_HOME: PROFILE_HOME }) }
+  );
+  return fs.existsSync(PROFILE_HOME);
+}
+
+function ensureProfile(session, io) {
+  if (!fs.existsSync(path.join(PROFILE_HOME, "config.yaml"))) {
+    if (!installProfileAssets(io)) return false;
+  }
+  writeRuntimeConfig(session); // always refresh the token/connection for this launch
+  return true;
+}
+
+// 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).
+function installedHermesVersion() {
+  try {
+    const init = path.join(AGENT_DIR, "hermes_cli", "__init__.py");
+    const m = fs.readFileSync(init, "utf8").match(/__version__\s*=\s*["']([^"']+)["']/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// 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 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");
+    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 null;
+    return tuiDir;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  ensureHermes,
+  ensureProfile,
+  brandedTuiDir,
+  hermesBin,
+  hermesInstalled,
+  launchEnv,
+  PROFILE,
+  PROFILE_HOME,
+};

package/src/cli.js

@@ -14,6 +14,7 @@
  */
 
 const COMMANDS = {
+  agent: () => require("./commands/agent"),
   login: () => require("./commands/login"),
   logout: () => require("./commands/logout"),
   whoami: () => require("./commands/whoami"),
@@ -46,6 +47,7 @@ const COMMANDS = {
 // suffix in the listing and reveal their full usage via `<command> --help`.
 
 const COMMAND_LIST = [
+  ["agent",          false, "Launch the DeepSQL Agent — interactive chat TUI (also: bare `deepsql`)"],
   ["login",          false, "Authorize this CLI with a DeepSQL instance"],
   ["logout",         false, "Revoke and forget the saved token"],
   ["whoami",         false, "Show the user behind the saved token"],
@@ -87,6 +89,16 @@ const GLOBAL_OPTIONS = [
 // constant; the dispatcher renders them on `<command> --help`.
 
 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)",
+    options: [
+      ["--url <url>",          "DeepSQL instance to use (default: saved login)"],
+      ["--connection <name>",  "Default connection for the session"],
+    ],
+    notes: "First run installs the agent runtime. Uses your saved `deepsql login` — no LLM key needed (the backend proxies the model).",
+  },
+
   login: {
     description: "Authorize this CLI with a DeepSQL instance.",
     usage: "deepsql login [options]",
@@ -650,7 +662,7 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   const stdout = io.stdout || process.stdout;
   const useColor = colorEnabled(stdout, rawArgv);
 
-  if (rawArgv.length === 0 || isHelpFlag(rawArgv[0])) {
+  if (isHelpFlag(rawArgv[0])) {
     stdout.write(`${renderRootHelp(useColor)}\n`);
     return 0;
   }
@@ -659,8 +671,14 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
     stdout.write(`${pkg.version}\n`);
     return 0;
   }
+  // No subcommand: launch the DeepSQL Agent TUI in an interactive terminal;
+  // fall back to the root help when stdout is piped/redirected (scripts, CI).
+  if (rawArgv.length === 0 && !stdout.isTTY) {
+    stdout.write(`${renderRootHelp(useColor)}\n`);
+    return 0;
+  }
 
-  const command = rawArgv[0];
+  const command = rawArgv.length === 0 ? "agent" : rawArgv[0];
   const loader = COMMANDS[command];
   if (!loader) {
     stderr.write(`Unknown command: ${command}\n\n${renderRootHelp(colorEnabled(stderr, rawArgv))}\n`);
@@ -668,7 +686,7 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   }
 
   // Per-command help: `deepsql <command> --help` / `-h` (anywhere in args).
-  const restArgs = rawArgv.slice(1);
+  const restArgs = rawArgv.length === 0 ? [] : rawArgv.slice(1);
   if (restArgs.some(isHelpFlag)) {
     stdout.write(`${renderCommandHelp(command, useColor)}\n`);
     return 0;
@@ -690,9 +708,17 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
     version: pkg.version,
   });
 
+  const previousExitCode = process.exitCode;
+  process.exitCode = undefined;
   try {
     const mod = loader();
-    await mod.run(opts, { stdout, stderr });
+    const commandCode = await mod.run(opts, { stdout, stderr });
+    if (typeof commandCode === "number") {
+      return commandCode;
+    }
+    if (typeof process.exitCode === "number" && process.exitCode !== 0) {
+      return process.exitCode;
+    }
     return 0;
   } catch (err) {
     stderr.write(`Error: ${err.message}\n`);
@@ -700,6 +726,12 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
       stderr.write(`${err.stack}\n`);
     }
     return 1;
+  } finally {
+    if (previousExitCode == null) {
+      process.exitCode = undefined;
+    } else {
+      process.exitCode = previousExitCode;
+    }
   }
 }
 

package/src/cli.test.js

@@ -73,6 +73,7 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const { main: _main } = require("./cli");
   void _main;
   const expected = [
+    "agent",
     "login","logout","whoami","config","mcp","connections","query","analyze","schema",
     "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
@@ -108,6 +109,13 @@ test("main rejects unknown commands and shows the root help", async () => {
   assert.match(io.err(), /Usage: deepsql/);
 });
 
+test("main preserves a non-zero command return code", async () => {
+  const io = captureStreams();
+  const code = await main(["connections", "current", "--url", "http://x", "--token", "t"], io);
+  assert.equal(code, 1);
+  assert.match(io.err(), /No active connection set/);
+});
+
 test("--no-color suppresses ANSI escapes in help output", async () => {
   const io = captureStreams();
   // Force a TTY so the only thing turning color off is --no-color itself.

package/src/commands/agent.js

@@ -0,0 +1,47 @@
+"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.
+
+const { spawn } = require("node:child_process");
+const { resolveSession } = require("./_session");
+const { ensureHermes, ensureProfile, hermesBin, launchEnv, PROFILE } = require("../agent/bootstrap");
+
+async function run(opts, io = {}) {
+  const stderr = io.stderr || process.stderr;
+
+  let session;
+  try {
+    session = resolveSession(opts);
+  } catch (e) {
+    stderr.write(`${e.message}\n`);
+    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;
+  }
+  if (!ensureProfile(session, io)) {
+    stderr.write("Could not provision the DeepSQL Agent profile.\n");
+    return 1;
+  }
+  // Branding is delivered via HERMES_TUI_DIR in launchEnv (Hermes runs our
+  // prebuilt branded TUI directly — no esbuild), set just below.
+
+  // Hand the terminal to the branded TUI (profile config sets interface=tui).
+  // launchEnv augments PATH (node/uv for the TUI + MCP server) and injects the
+  // provider vars that keep Hermes' first-run guard from ever firing.
+  const child = spawn(hermesBin(), ["-p", PROFILE, "--tui"], { stdio: "inherit", env: launchEnv(session) });
+  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);
+    });
+  });
+}
+
+module.exports = { run };

package/src/commands/connections.js

@@ -333,10 +333,11 @@ async function runTest(opts, { stdout = process.stdout, stderr = process.stderr
       throw new Error("Usage: deepsql connections test <name> | --from-file <path>");
     }
     const connectionId = await resolveConnectionId(session, target);
-    cfg = await findConnectionRecord(session, connectionId);
-    if (!cfg) throw new Error(`Connection ${target} not found.`);
-    // Backend's POST /connections/test uses saved secrets when `id` is set.
-    cfg.id = connectionId;
+    // Send only the id for saved connections. The list/show APIs intentionally
+    // omit secrets, so posting that masked summary back to /connections/test
+    // breaks SSH/SSL/password-backed connections. The backend hydrates the
+    // saved decrypted config when an id is present.
+    cfg = { id: connectionId };
   }
 
   const result = await request(session.baseUrl, "/connections/test", {
@@ -352,7 +353,9 @@ async function runTest(opts, { stdout = process.stdout, stderr = process.stderr
   printPrivilegeReport(stdout, result);
   if (!result?.connectionSuccessful) {
     process.exitCode = 1;
+    return 1;
   }
+  return 0;
 }
 
 // ─── show ──────────────────────────────────────────────────────────────────