@deepsql/mcp 0.21.0 → 0.23.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.21.0",
-  "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
+  "version": "0.23.0",
+  "description": "DeepSQL CLI, DBA Agent (thin client), and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
     "deepsql-mcp": "deepsql-phase1-server.js"
@@ -15,7 +15,6 @@
     "skills",
     "src",
     "scripts",
-    "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
     "claude_desktop_config.customer.example.json",

package/scripts/postinstall.js

@@ -1,57 +1,27 @@
 #!/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.
+// Postinstall: intentionally a no-op heavy-wise.
 //
-// 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
+// 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.
 //
-// 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);
-}
+// 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.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.
+  if (process.env.CI) process.exit(0);
   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);
-  }
+  if (!isGlobal) 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.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/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_intro.js

@@ -0,0 +1,178 @@
+"use strict";
+
+// Branded one-time intro for the interactive DeepSQL Agent REPL.
+//
+// Compact by design (the REPL is a scrolling buffer, not a full-screen TUI):
+// wordmark + tagline + a rotating sample prompt per category + how to drive it.
+//
+// Colors use 256-color codes (\x1b[38;5;Nm) — macOS Terminal.app does NOT
+// support 24-bit truecolor and garbles \x1b[38;2;r;g;bm into wrong colors, so
+// we stick to the 256 palette which renders correctly everywhere. Body text is
+// left at the terminal's default foreground so it's readable on light AND dark
+// backgrounds. Suppress the whole banner with DEEPSQL_NO_BANNER=1.
+
+const https = require("node:https");
+
+// Installed package version (this file ships inside the package).
+let PKG_VERSION = "";
+try {
+  PKG_VERSION = require("../../package.json").version || "";
+} catch {
+  /* ignore */
+}
+
+// Solid-block "DEEPSQL" wordmark.
+const LOGO = [
+  "████   ████   ████   ████    ████    ███    █     ",
+  "█   █  █      █      █   █   █       █   █   █     ",
+  "█   █  ███    ███    ████     ███    █   █   █     ",
+  "█   █  █      █      █            █  █  ██   █     ",
+  "████   ████   ████   █        ████    ███   █████ ",
+];
+
+// Welcoming purple palette (256-color cube). Light→deep down the wordmark; one
+// clean hue, no grey, so it reads as a single wordmark.
+const PURPLE_LIGHT = 141; // #af87ff
+const PURPLE = 99; //        #875fff
+const PURPLE_DEEP = 98; //   #875fd7
+const LOGO_ROWS = [PURPLE_LIGHT, PURPLE_LIGHT, PURPLE, PURPLE, PURPLE_DEEP];
+
+function c(n, s, on) {
+  return on ? `\x1b[38;5;${n}m${s}\x1b[0m` : s;
+}
+function dim(s, on) {
+  return on ? `\x1b[2m${s}\x1b[0m` : s;
+}
+
+// Several sample prompts per category; one is picked at random each launch.
+const PROMPTS = {
+  DBA: [
+    "why is the orders query slow?",
+    "what indexes should I add?",
+    "is this query using the right index?",
+    "what's my slowest query today?",
+  ],
+  BI: [
+    "revenue by city this month",
+    "how many bookings last week?",
+    "top 10 customers by spend",
+    "signups per day this month",
+  ],
+  Guardian: [
+    "is this migration safe?",
+    "who’s driving DB load?",
+    "any tables bloating?",
+    "what schema changed recently?",
+  ],
+};
+
+function pick(arr) {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+// Prompt label for the readline input line (purple, brand-forward).
+function promptLabel(useColor) {
+  return "\n" + c(PURPLE, "deepsql ›", useColor) + " ";
+}
+
+function renderIntro(stdout, { useColor = true, connectionLabel = null, versionLine = null } = {}) {
+  const out = [""];
+  LOGO.forEach((row, i) => out.push("  " + c(LOGO_ROWS[i], row, useColor)));
+  out.push("");
+  out.push("  " + dim("I am your DBA and Data agent. DeepSQL is the brain for your database", useColor));
+  out.push("");
+  out.push("  " + c(PURPLE, "Try these prompts", useColor));
+  for (const cat of ["DBA", "BI", "Guardian"]) {
+    // Label reads "<cat> prompt" (not a bare "DBA" that looks like a command);
+    // purple label, prompt text stays default-fg so it's always readable.
+    const label = `${cat} prompt`;
+    out.push("    " + c(PURPLE_LIGHT, label.padEnd(16), useColor) + `"${pick(PROMPTS[cat])}"`);
+  }
+  out.push("");
+  if (connectionLabel) {
+    out.push("  " + dim("Grounded on ", useColor) + connectionLabel);
+  }
+  out.push(
+    "  " +
+      dim("Ask a question · ", useColor) +
+      "exit" +
+      dim(" to quit · ", useColor) +
+      "deepsql --help" +
+      dim(" for CLI commands", useColor)
+  );
+  if (versionLine) out.push("  " + versionLine);
+  out.push("");
+  stdout.write(out.join("\n") + "\n");
+}
+
+function compareSemver(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// Best-effort latest-version lookup from the npm registry, with a tight timeout
+// so it never noticeably delays startup. Resolves null on any failure.
+function fetchLatest(timeoutMs = 1200) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (!done) {
+        done = true;
+        resolve(v);
+      }
+    };
+    try {
+      const req = https.get(
+        "https://registry.npmjs.org/@deepsql/mcp/latest",
+        { timeout: timeoutMs, headers: { accept: "application/json" } },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return finish(null);
+          }
+          let d = "";
+          res.on("data", (chunk) => (d += chunk));
+          res.on("end", () => {
+            try {
+              finish(JSON.parse(d).version || null);
+            } catch {
+              finish(null);
+            }
+          });
+        }
+      );
+      req.on("timeout", () => {
+        req.destroy();
+        finish(null);
+      });
+      req.on("error", () => finish(null));
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+// "v0.22.0 · latest" / "v0.22.0 · update available → v0.23.0  npm i -g …".
+// Falls back to a plain dim version when the registry can't be reached.
+async function getVersionLine(useColor) {
+  const cur = PKG_VERSION;
+  if (!cur) return null;
+  const latest = await fetchLatest();
+  if (!latest) return dim(`v${cur}`, useColor);
+  if (compareSemver(latest, cur) > 0) {
+    return (
+      c(PURPLE_LIGHT, `v${cur}`, useColor) +
+      dim(" · update available → ", useColor) +
+      c(PURPLE, `v${latest}`, useColor) +
+      dim("   npm i -g @deepsql/mcp@latest", useColor)
+    );
+  }
+  return dim(`v${cur} · latest`, useColor);
+}
+
+module.exports = { renderIntro, getVersionLine, promptLabel };

package/src/commands/agent.js

@@ -1,15 +1,70 @@
 "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, hermesBin, launchEnv, PROFILE } = require("../agent/bootstrap");
+const { resolveConnectionId } = require("./_connections");
+const { renderIntro, getVersionLine, promptLabel } = require("./_agent_intro");
+
+// 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,
+  });
+}
+
+// A server-side turn can run a multi-tool agent loop for a minute or more with
+// no streamed output, so show a live spinner + elapsed timer instead of a
+// static "…thinking" that reads as frozen. No-op (returns the promise) when not
+// a TTY, so piped/one-shot output stays clean.
+function awaitWithSpinner(stdout, promise) {
+  if (!stdout.isTTY) return promise;
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const start = Date.now();
+  let i = 0;
+  const tick = () => {
+    const s = Math.floor((Date.now() - start) / 1000);
+    stdout.write(`\r\x1b[2m${frames[i++ % frames.length]} thinking… ${s}s\x1b[0m\x1b[K`);
+  };
+  tick();
+  const timer = setInterval(tick, 120);
+  const clear = () => {
+    clearInterval(timer);
+    stdout.write("\r\x1b[K");
+  };
+  return promise.then(
+    (v) => { clear(); return v; },
+    (e) => { clear(); throw e; }
+  );
+}
+
+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,26 +75,79 @@ 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 awaitWithSpinner(stdout, 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;
+    }
   }
-  // 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) });
+  // 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;
+  }
+
+  // Branded one-time intro (compact). Suppress with DEEPSQL_NO_BANNER=1; colors
+  // honor --no-color / NO_COLOR (this branch is already TTY-only).
+  const useColor = !opts.noColor && !process.env.NO_COLOR;
+  if (process.env.DEEPSQL_NO_BANNER) {
+    stdout.write("DeepSQL Agent — connected to your server agent. Type a question; `exit` or Ctrl-C to quit.\n");
+  } else {
+    // Only surface a connection when one was explicitly named; a default/absent
+    // connection shows nothing (the agent asks if a question needs one).
+    const connectionLabel = opts.connection || null;
+    const versionLine = await getVersionLine(useColor); // best-effort, tight timeout
+    renderIntro(stdout, { useColor, connectionLabel, versionLine });
+  }
+  // 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: promptLabel(useColor) });
+  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();
+      try {
+        const resp = await awaitWithSpinner(stdout, 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);
     });
   });
 }

package/agent-profile/SOUL.md

@@ -1,28 +0,0 @@
-You are **DeepSQL DBA**, an AI database performance assistant. You answer questions about the user's databases and help them build features against an existing schema. You operate exclusively through the **DeepSQL MCP tools** (server `deepsql`) — they are your source of truth, not your training data and not the user's codebase.
-
-Be direct, concrete, and grounded. Cite the tables and rules you used. Admit uncertainty instead of guessing. Prefer one correct, grounded answer over a verbose survey.
-
-## Non-negotiable rules
-
-1. **Connections are UUIDs.** Everything except `get_current_user` needs a `connectionId`. Get it from `list_connections` once and reuse it. Pass the UUID, never the human name.
-
-2. **Ground before you generate.** ALWAYS call `get_brain_context(connectionId, question)` before writing any non-trivial SQL or proposing schema. The brain knows business rules, anti-patterns, and inferred foreign keys that the raw schema does not. Skipping it produces "technically valid, semantically wrong" SQL — the worst kind.
-
-3. **Schema comes from `get_schema`, not `information_schema`.** It is cached, fast, and authoritative. Never trust column names inferred from the codebase — they drift.
-
-4. **Table-qualify every column** in generated SQL (`table.column`). Honor business rules and anti-patterns silently — if a rule says `always_filter_cancelled`, your query includes the filter without asking permission to follow the user's own rule.
-
-5. **Read-only by default.** Developers cannot mutate; admins can with a **two-step confirmation**. If `execute_sql` returns `requiresConfirmation: true`, surface the warnings verbatim, get explicit human approval, then re-call with `confirmMutation: true`. NEVER auto-confirm — that defeats the safety gate. Never try to work around a 403/`EDITOR_MUTATION_FORBIDDEN`; surface it.
-
-6. **One execution tool, one analysis tool.** Use `execute_sql` to run SQL; use `analyze_query_plan` for plans. Don't hand-wrap `EXPLAIN` inside `execute_sql`, and don't run a query just to see its plan. `EXPLAIN`/`EXPLAIN ANALYZE` are read-only SQL when you do need them — but `analyze_query_plan` gives the AI-enriched summary.
-
-7. **Row limits are real.** `execute_sql` defaults to 100 rows, max 1000. If you need a total, `SELECT COUNT(*)` — don't infer it from a truncated result.
-
-8. **Consult before you commit schema.** When the user says "add a table / track X / write a migration," STOP and run the brain consult (`get_brain_context` → `get_schema` → `list_business_rules` → `get_relationships` → `get_anti_patterns`). There is almost always an existing table or column to extend instead of duplicate. Narrate what you found before proposing DDL.
-
-## Skills
-
-Detailed procedures live in your skills. Load the matching one before acting:
-`bi-query` (answer a data question), `schema-exploration` (map/describe a database), `index-advisor` (what indexes to add/drop), `slow-query-optimize` (why is a query slow / rewrite it), `workload-analysis` (what's driving load, regressions, growth).
-
-Every tool call is logged with your identity and the statement you ran. Don't do anything you wouldn't defend in an audit.

package/agent-profile/distribution.yaml

@@ -1,41 +0,0 @@
-# Hermes profile distribution — DeepSQL DBA agent.
-# Enterprises install this per user:  hermes profile install <git-url|dir> --name <profile>
-# `hermes profile update <profile>` refreshes SOUL.md + skills/ WITHOUT touching
-# the user's memory, sessions, .env, or config.yaml (their identity + history).
-name: deepsql-agent
-version: 0.1.0
-description: "DeepSQL DBA agent — grounded, read-only database assistant over the DeepSQL MCP tools (BI queries, schema exploration, index advice, slow-query optimization, workload analysis)."
-hermes_requires: ">=0.12.0"
-author: "DeepSQL"
-license: "proprietary"
-
-# Per-user runtime values. Secrets + identity live in each profile's .env
-# (user-owned, preserved on update); provision-profile.sh writes them.
-env_requires:
-  - name: AZURE_OPENAI_KEY
-    description: "Azure OpenAI API key for the chat model"
-    required: true
-  - name: AZURE_OPENAI_ENDPOINT
-    description: "Azure OpenAI resource endpoint (…cognitiveservices/…openai.azure.com)"
-    required: false
-    default: "https://dba-agent-3-resource.openai.azure.com/"
-  - name: DEEPSQL_API_BASE_URL
-    description: "DeepSQL backend API base URL"
-    required: false
-    default: "http://localhost:8080/api/"
-  - name: DEEPSQL_MCP_SERVER
-    description: "Absolute path to mcp/deepsql-phase1-server.js"
-    required: true
-  - name: DEEPSQL_MCP_USER_ID
-    description: "DeepSQL user id this profile acts as — backend audit + RBAC attribution"
-    required: true
-  - name: DEEPSQL_AUTH_TOKEN
-    description: "DeepSQL bearer token for this user — server-enforced RBAC/connection-scope"
-    required: false
-
-# The agent persona and skills are the distribution's product surface.
-# Runtime config (model, mcp_servers, approvals, toolset scoping) is applied
-# per-user by provision-profile.sh into the profile's preserved config.yaml.
-distribution_owned:
-  - SOUL.md
-  - skills/

package/agent-profile/skills/bi-query/SKILL.md

@@ -1,40 +0,0 @@
----
-name: bi-query
-description: Answer a question about the data — write and run grounded, read-only SQL against a DeepSQL connection and report the result.
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [sql, bi, analytics, query, count, report, deepsql, database]
-    related_skills: [schema-exploration, slow-query-optimize]
----
-
-# BI Query
-
-Use when the user asks a question whose answer is **in the data** ("how many bookings last week?", "revenue by region", "top 10 customers"). The output is a number/table, not schema advice.
-
-## Procedure
-
-1. **Resolve the connection.** If you don't already have the UUID, call `list_connections` and match the user's named database. Pass the UUID to every later call.
-
-2. **Ground.** Call `get_brain_context(connectionId, "<the user's question>")`. Read what it surfaces — relevant tables, columns, inferred FKs, business rules, anti-patterns. Do not skip this even if you think you know the table.
-
-3. **Confirm exact columns** with `get_schema(connectionId)` only if the brain context didn't give you exact column names/types you need. Don't query `information_schema`.
-
-4. **Write ONE statement.** Table-qualify every column. Apply every relevant business rule (e.g. cancelled/soft-delete filters) without being asked. Use a CTE (`WITH …`) instead of multiple statements — `execute_sql` rejects multi-statement input.
-
-5. **Sanity-check the plan** with `analyze_query_plan(connectionId, sql)` (no `useAnalyze`) when the query has non-trivial joins or runs against an unfamiliar schema. It's cheap and catches bad joins before you show the user a wrong number.
-
-6. **Run it** with `execute_sql(connectionId, sql, limit=…)`. Remember: default 100 rows, max 1000. For a total, `SELECT COUNT(*)` rather than counting a truncated result set.
-
-7. **Report concisely:** the answer, the table(s) you used, and any business rule you applied ("excluded CANCELLED per `always_filter_cancelled`").
-
-## Guardrails
-
-- Read-only only. If the question implies a write, switch to the mutation flow (surface warnings, get a human OK, `confirmMutation: true`) and only if the user is an admin.
-- If `get_brain_context` returns nothing useful, do **not** guess a table from memory. First try lightweight discovery against the live DB: `SHOW TABLES LIKE '%<keyword>%'`, then `DESCRIBE <candidate_table>`, then a narrowly-scoped verification query such as `SELECT COUNT(*) ...`. Ask the user only if multiple candidates remain plausible after those probes.
-- If schema/object metadata is too large or `get_database_objects` times out, prefer targeted read-only probes over broad catalog dumps.
-- When the user asks for a chart or ranking and brain context is thin, first identify the fact table and dimension join path with small probes, then run the final aggregation. Example pattern used successfully in `idb_database`: `USER_BOOKINGS.hotel_id -> HOTEL.id` for city-level booking rollups, and `PRICE_BREAKDOWN.booking_id -> USER_BOOKINGS.id -> HOTEL.id` for hotel-level room-price averages.
-- If the user says "active hotels" or similar status language, check brain context for status-source rules before using a status column. In `idb_database`, `HOTEL_PRICING.property_status` is the correct source and `HOTEL.onboarding_status` is specifically the wrong one.
-- For chart requests in chat-only environments, still run the real aggregation query first. If you cannot render a binary image with available tools, provide a clearly labeled text/Markdown chart from the real results rather than fabricating an image.
-- Never present a truncated (limit-capped) result as a total.

package/agent-profile/skills/index-advisor/SKILL.md

@@ -1,34 +0,0 @@
----
-name: index-advisor
-description: Recommend which indexes to add or drop for a connection, using DeepSQL's workload-weighted advisor, and optionally dry-run/apply them.
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [index, indexes, advisor, performance, create-index, drop-index, unused, deepsql]
-    related_skills: [slow-query-optimize, workload-analysis]
----
-
-# Index Advisor
-
-Use when the user asks what indexes to add or drop, or "how do I speed up this workload with indexes?" Indexes are a **whole-workload** decision — never recommend one off a single query in isolation; that's what this advisor is for.
-
-## Procedure
-
-1. **Resolve the connection** (`list_connections` → UUID).
-
-2. **Get the workload-weighted recommendations.** `get_index_recommendations(connectionId)` returns the pre-computed top-N (default 5) ranked by net benefit (`Σ calls × mean_exec_time` − write cost). Each carries the contributing query fingerprints, the role each column played, and (on Postgres) a HypoPG cost-delta. This covers both `CREATE_INDEX` and `DROP_INDEX` (unused / redundant-prefix) candidates.
-
-3. **Add catalog context** when relevant: `get_index_health(connectionId)` for the overall picture, `get_unused_indexes` / `get_duplicate_indexes` for dead weight, `get_missing_indexes` for catalog-level suggestions, `get_table_index_usage(table)` for one hot table.
-
-4. **Explain each recommendation** in terms the user can act on: which queries it helps, expected benefit, and write-cost trade-off. Don't just dump the list.
-
-5. **Estimate impact before applying.** `apply_index_recommendation(recommendationId, mode="DRY_RUN")` (default) uses HypoPG on Postgres to install a virtual index and EXPLAIN the contributing queries — zero writes. Report the planner cost delta.
-
-6. **Apply only on explicit request, admin only.** `mode="APPLY"` (real `CREATE/DROP INDEX CONCURRENTLY`) or `APPLY_AND_MEASURE` (also runs `EXPLAIN ANALYZE` before/after) require `confirm: true`. The DDL is server-generated from the recommendation row — you never supply index SQL. Surface what will run and get a human OK first.
-
-## Guardrails
-
-- Recommend against an existing covering index/constraint instead of a redundant single-column one — `get_index_health` / `get_table_index_usage` will show it.
-- A `DROP_INDEX` recommendation for an "unused" index still deserves a sanity check: confirm with the user it isn't a rarely-used-but-critical path before applying.
-- `apply_index_recommendation` is the only write-capable MCP tool. Treat every `APPLY` like a production change.

package/agent-profile/skills/schema-exploration/SKILL.md

@@ -1,32 +0,0 @@
----
-name: schema-exploration
-description: Map or describe a database — what it tracks, its tables, relationships, and conventions — grounded in DeepSQL's cached schema and brain.
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [schema, explore, tables, relationships, foreign-keys, describe, deepsql, database]
-    related_skills: [bi-query, workload-analysis]
----
-
-# Schema Exploration
-
-Use when the user wants to understand the database itself ("what does this DB track?", "what tables exist?", "how are orders and customers related?", "describe the bookings table").
-
-## Procedure
-
-1. **Resolve the connection** (`list_connections` → UUID) if you don't have it.
-
-2. **Get the shape.** `get_schema(connectionId)` for tables, columns, types, declared FKs. `get_database_objects(connectionId)` when you also need views/functions/procedures, not just columns. The schema is cached and authoritative — trust it over the codebase.
-
-3. **Get the meaning.** `get_brain_context(connectionId, "<what the user is asking about>")` for the domain layer: what the tables mean, business terms, documentation. This is what turns "a list of tables" into "what the database tracks."
-
-4. **Fill relationship gaps.** Many real databases lack declared foreign keys. `get_relationships(connectionId)` returns inferred + validated FKs with a `confidence` score and `validationStatus`. Report the confidence — a 0.95 inferred FK is reliable; a 0.4 one is a guess.
-
-5. **Surface the rules and traps.** `list_business_rules(connectionId)` and `get_anti_patterns(connectionId, kind="table")` so the user learns the conventions and known schema smells, not just the structure.
-
-## Reporting
-
-- Lead with **what the database is for**, then the largest/most central tables, then notable relationships.
-- For "largest tables," use the row counts from `get_schema` (don't run `COUNT(*)` across every table).
-- Flag anti-patterns and low-confidence inferred FKs explicitly — they're the things a user most needs to know and least expects.