diff --git a/AGENTS.md b/AGENTS.md index 9a97c91..bd2cc43 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -178,8 +178,9 @@ only covers cloud-specific, non-obvious caveats. - **Backend** (port 8080, base path `/api`): `bash scripts/start-backend.sh` (wraps `./mvnw spring-boot:run`; it strips `SPRING_PROFILES_ACTIVE=prod` for local runs → dev mode). - **Frontend** (port 3000): `npm run dev` (Vite proxies `/api` → 8080 and `/agent-api` → 8787). -- **Hermes Agent webui** (port 8787, optional): needed only for the sidebar **Agent** tab. - See caveats below for install + `HERMES_WEBUI_ALLOWED_ORIGINS`. +- **DeepSQL Agent API** (port 8787, optional): needed for the sidebar **Agent** tab. + Runtime is a customized Nous Hermes Agent; see caveats below for install + + `HERMES_WEBUI_ALLOWED_ORIGINS` (upstream env name). - A demo target DB `demo_shop` (same Postgres server, sample `customers`/`products`/`orders`) exists for exercising connection/schema features without an external database. @@ -207,15 +208,19 @@ only covers cloud-specific, non-obvious caveats. `DEEPSQL_CHAT_ENDPOINT=https://deepsql-selfhost-resource.cognitiveservices.azure.com/`, `DEEPSQL_CHAT_MODEL=gpt-5.4` (deployment name), plus matching `DEEPSQL_EMBEDDING_*` with `text-embedding-3-large`. Also set `AZURE_OPENAI_KEY` / `AZURE_OPENAI_ENDPOINT` aliases — - `hermes/install.sh` reads those. After changing LLM env, restart the backend + `agent/install.sh` reads those. After changing LLM env, restart the backend (`scripts/start-backend.sh`); `/api/setup/status` should show `hasLlmConfig: true`. -- **Agent tab (Hermes) is optional but required for the in-app Agent chat UI.** Install via +- **Agent tab is optional but required for the in-app Agent chat UI.** The Agent tab + is DeepSQL’s own React (`AgentChatPanel`); it talks to the DeepSQL Agent HTTP API + on `:8787` (a heavily customized [Nous Hermes Agent](https://hermes-agent.nousresearch.com/) + runtime — see [`agent/README.md`](agent/README.md)). Install upstream via `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-setup`, - symlink `~/.hermes/hermes-agent/.venv` → `venv` (DeepSQL's `hermes/install.sh` expects `.venv`), - then `bash hermes/install.sh`. Start the webui with + symlink `~/.hermes/hermes-agent/.venv` → `venv` (DeepSQL’s `agent/install.sh` expects `.venv`), + then `bash agent/install.sh`. Start the agent API/webui with `HERMES_WEBUI_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000` - (without this, Vite's Origin header makes Hermes return **403** "Cross-origin mismatch"). - Webui listens on `:8787`; Vite proxies `/agent-api` → there. + (upstream env var; without it Vite’s Origin header yields **403** “Cross-origin mismatch”). + Listens on `:8787`; Vite proxies `/agent-api` → there. Profile cookie name + `hermes_profile` is an upstream contract — do not rename it in DeepSQL clients. - **Before running backend tests that boot the Spring context** (e.g. `ApiSmokeTest`), stop the running backend first — both use `ddl-auto=update` on the same `dba_agent` DB and can deadlock on an `ALTER TABLE`. Test env vars are documented in `CLAUDE.md` (Testing). diff --git a/CLAUDE.md b/CLAUDE.md index 9070d6a..17dd063 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,6 +90,7 @@ src/ # Frontend (React) docs/ # Documentation mcp/ # DeepSQL Phase 1 MCP server (Node stdio wrapper around backend APIs) +agent/ # DeepSQL Agent customization (persona, skills, skins; customized Hermes runtime) ``` ## MCP Server @@ -103,10 +104,11 @@ mcp/ # DeepSQL Phase 1 MCP server (Node stdio wrapper around back ## Dashboard Generation (artifact model) -Dashboards are **generated by the embedded Hermes agent acting as a coding agent** — it writes the whole dashboard as a single self-contained HTML document, not a JSON spec. The earlier spec+renderer model (metrics/charts/tables + a `{{placeholder}}` substitution engine + `DashboardBuilder.js`) was thrown away: the rigid `col BETWEEN {{name}}` convention couldn't express real SQL (e.g. a Unix-epoch date filter → `near '{range.start}'` syntax errors) and boxed the agent in. +Dashboards are **generated by the embedded DeepSQL Agent acting as a coding agent** +(customized Hermes runtime — see [`agent/README.md`](agent/README.md)) — it writes the whole dashboard as a single self-contained HTML document, not a JSON spec. The earlier spec+renderer model (metrics/charts/tables + a `{{placeholder}}` substitution engine + `DashboardBuilder.js`) was thrown away: the rigid `col BETWEEN {{name}}` convention couldn't express real SQL (e.g. a Unix-epoch date filter → `near '{range.start}'` syntax errors) and boxed the agent in. - `DashboardAgentService` is a thin broker: `ensureProfileForUser` → `ensureSession` (fresh session) → `sendAndAwait` with an **artifact contract**. The agent grounds on the brain/schema, verifies every query with `execute_sql`, then emits ONE HTML doc (in a ` ```html ` block). The broker extracts the HTML and returns `{version:3, renderMode:"artifact", title, html, trace}`, stored verbatim in `saved_dashboards.dashboardConfig`. -- The agent loads the **`dashboard-design` skill** (`hermes/skills/dashboard-design/SKILL.md`, v2 — artifact contract, the `deepsql.query` runtime, composition/UX rules, an **intent checklist**, and Unix-epoch date handling). +- The agent loads the **`dashboard-design` skill** (`agent/skills/dashboard-design/SKILL.md`, v2 — artifact contract, the `deepsql.query` runtime, composition/UX rules, an **intent checklist**, and Unix-epoch date handling). - **Rendering + data access**: `DashboardArtifact.jsx` renders the HTML in a **sandboxed iframe** (`sandbox="allow-scripts"`, opaque origin + a strict CSP — no external network). The artifact fetches data only through an injected `deepsql.query(sql)` bridge that `postMessage`s to the parent; the parent calls **`POST /api/dashboards/query`** (`DashboardQueryController`), which is **read-only twice over** (`McpSqlGuardService.validateReadOnlySql` + `QueryExecutionContext.api` = `READ_ONLY_ONLY`) and access-scoped via `assertCanReadConnectionContent`. So the agent's code has full creative freedom while every query stays guarded and sandboxed. The bridge also auto-sizes the iframe and forwards runtime errors. - Generation endpoints unchanged (`POST /api/dashboards/generate` + `/generate/stream`). `DashboardBuilder.js`/`DashboardInputs.js` remain only because `tabs/Core/PreviewTab.js` still uses them — the dashboard *creation* path no longer touches them. - **Sharing**: both share types render a standalone read-only `DashboardViewer` (title + `DashboardArtifact` with an injected `queryFn`). Internal link `/dashboard-view/:id` (auth) uses the authed broker; public link `/share/dashboard/:token` (permitAll) uses `PublicDashboardController` (`GET /api/public/dashboards/{token}` + `/query`), which resolves only while `saved_dashboards.is_public` is true (revoke = flip it) and runs read-only + connection-scoped. `share_token`/`is_public` are set only via `POST|DELETE /api/saved-dashboards/{id}/share` (access-checked), never a general update. `ShareMenu.jsx` drives the UI. The public query path has its own nginx `dashq` limiter. diff --git a/agent/README.md b/agent/README.md new file mode 100644 index 0000000..0c1b1c4 --- /dev/null +++ b/agent/README.md @@ -0,0 +1,81 @@ +# DeepSQL Agent + +Source of truth for the **DeepSQL Agent** — DeepSQL’s DBA-specialized agent layer: +persona, skills, skins, and install overlays. + +## Upstream disclosure + +The runtime is a **heavily customized [Nous Hermes Agent](https://hermes-agent.nousresearch.com/)** +(plus its optional webui/TUI). DeepSQL does not ship a fork of that runtime in this +tree. Instead this directory is the product surface we own: + +| DeepSQL customization | Purpose | +|-----------------------|---------| +| `SOUL.md` | DBA persona / always-on system prompt (grounding, RBAC, read-only defaults) | +| `skills/*/SKILL.md` | DBA procedures (BI query, schema, indexes, slow queries, workload, dashboards) | +| `skins/deepsql.yaml` | CLI/TUI skin | +| `webui/` | Optional overlay that rebrands a Hermes webui checkout to DeepSQL | +| `tui/` | Optional overlay that rebrands the Hermes TUI checkout to DeepSQL | +| `install.sh` / `distribution.yaml` | Idempotent install + enterprise profile distribution | + +Upstream install paths and CLI names (`~/.hermes`, `hermes` binary, `HERMES_*` env +vars, `hermes_profile` cookie, skill frontmatter `metadata.hermes`) are **unchanged** — +those are contracts of the upstream engine. Product UI and docs refer to the +**DeepSQL Agent**, not Hermes. + +The in-app Agent tab is DeepSQL’s own React (`AgentChatPanel`); it consumes the +agent HTTP API (`/agent-api/*`), not the Hermes webui skin. + +## Contents + +- `SOUL.md` — DBA persona. Encodes DeepSQL grounding discipline (`get_brain_context` + before SQL, table-qualified columns, business rules + anti-patterns, read-only by + default, two-step mutation confirm). +- `skills//SKILL.md` — procedural skills (agentskills.io format): + - `bi-query` — answer a data question with grounded, read-only SQL + - `schema-exploration` — map/describe a database + - `index-advisor` — recommend (and dry-run/apply) indexes via the workload-weighted advisor + - `slow-query-optimize` — diagnose + rewrite one slow query + - `workload-analysis` — hotspots, regressions, per-customer load, growth + - `dashboard-design` — HTML dashboard artifact contract for the coding-agent path +- `distribution.yaml` — profile distribution for `hermes profile install/update` +- `webui/`, `tui/`, `skins/` — optional branding overlays for upstream UIs + +These mirror workflows the in-house `AgentOrchestrator` performed, re-expressed as +agent persona + skills over the DeepSQL MCP tools. + +## Install (local / self-host) + +1. Install the upstream agent runtime (see [AGENTS.md](../AGENTS.md) Cursor Cloud notes + or the [Hermes install docs](https://hermes-agent.nousresearch.com/)). +2. Apply DeepSQL customization (requires `AZURE_OPENAI_KEY` in the environment or + the repo `.env`): + +```bash +bash agent/install.sh +``` + +It configures `~/.hermes/config.yaml` from this repo: + +- **model** — Azure OpenAI via its OpenAI-compatible `…/openai/v1` endpoint (key from env/.env, never committed) +- **mcp_servers.deepsql** — this repo’s `mcp/deepsql-phase1-server.js` +- **skills.external_dirs** — this repo’s `agent/skills` (source of truth; must be a YAML list) +- **approvals.mode: smart**, **SOUL.md** persona, and disables host-affecting toolsets + (terminal/file/code/browser/computer_use) → a read-only `deepsql:*` + memory/todo/skills sandbox + +Verify: + +```bash +cd ~/.hermes/hermes-agent && uv run hermes mcp test deepsql # → Connected, DeepSQL tools +``` + +The DeepSQL MCP server and the Spring backend remain the DBA brain; the agent consumes them. +Optional upstream webui skin: see [`webui/`](webui/). + +### Approval UX (operator note) + +Because every exposed tool is read-only (`deepsql:*` reads; the one write tool, +`apply_index_recommendation`, is server-side `confirm`-gated; host toolsets disabled), +webui per-call approval prompts add friction without adding safety for this deployment. +Operators can enable session auto-approve (or per-tool “Always allow”) so DBA turns +flow without clicking. Left as a deliberate operator action, not a baked-in default. diff --git a/hermes/SOUL.md b/agent/SOUL.md similarity index 95% rename from hermes/SOUL.md rename to agent/SOUL.md index 803722c..97edcd7 100644 --- a/hermes/SOUL.md +++ b/agent/SOUL.md @@ -55,8 +55,9 @@ before acting: `bi-query` (answer a data question), `schema-exploration` ## Voice You are **DeepSQL**. Never refer to yourself, your skills, your memory, or your -runtime as "Hermes" — that is the underlying engine and is invisible to the -user. They are **DeepSQL skills**, the **DeepSQL agent**, the **DeepSQL brain**. +runtime as "Hermes" in user-facing replies — users see the **DeepSQL Agent**. +(Operators know the runtime is a customized Nous Hermes Agent; that detail stays +out of chat.) They are **DeepSQL skills**, the **DeepSQL agent**, the **DeepSQL brain**. Don't surface internal filesystem paths (`~/.hermes/...`) or engine internals; speak in DeepSQL product terms. diff --git a/hermes/distribution.yaml b/agent/distribution.yaml similarity index 92% rename from hermes/distribution.yaml rename to agent/distribution.yaml index 886ba78..f9b57c8 100644 --- a/hermes/distribution.yaml +++ b/agent/distribution.yaml @@ -1,7 +1,8 @@ -# DeepSQL Agent profile distribution. +# DeepSQL Agent profile distribution (runs on the Nous Hermes Agent profile CLI). # Enterprises install this per user: hermes profile install --name # `hermes profile update ` refreshes SOUL.md + skills/ WITHOUT touching # the user's memory, sessions, .env, or config.yaml (their identity + history). +# `hermes_requires` is an upstream schema key — do not rename it. 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)." diff --git a/hermes/install.sh b/agent/install.sh similarity index 82% rename from hermes/install.sh rename to agent/install.sh index 95e0903..dd67978 100755 --- a/hermes/install.sh +++ b/agent/install.sh @@ -1,17 +1,20 @@ #!/usr/bin/env bash -# Reproducibly install the DBA customization into an agent home (~/.hermes). -# Idempotent: safe to re-run. Source of truth is this repo's hermes/ dir. +# Reproducibly install the DeepSQL Agent customization into an agent home (~/.hermes). +# Idempotent: safe to re-run. Source of truth is this repo's agent/ dir. # # Configures: # - model: existing Azure OpenAI gpt-5.4 via its OpenAI-compatible v1 endpoint # - mcp_servers.deepsql: the repo's DeepSQL MCP server (read-only DBA tools) -# - skills.external_dirs: this repo's hermes/skills (source of truth) +# - skills.external_dirs: this repo's agent/skills (source of truth) # - approvals.mode: smart # - SOUL.md: the DBA persona # - disables host-affecting toolsets (terminal/file/code/browser/computer_use) # # Secrets are read from the environment (or the repo .env), never committed: # AZURE_OPENAI_KEY, AZURE_OPENAI_ENDPOINT (endpoint defaults to the repo value) +# +# Upstream note: HERMES_HOME / hermes-agent / hermes CLI are contracts of the +# Nous Hermes Agent runtime this customization runs on — do not rename those. set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -50,14 +53,14 @@ cfg.setdefault("mcp_servers", {})["deepsql"] = { "env": {"DEEPSQL_API_BASE_URL": "http://localhost:8080/api/", "DEEPSQL_MCP_USER_ID": "deepsql-agent", "DEEPSQL_MCP_PROJECT_ID": "deepsql-agent"}, } -cfg.setdefault("skills", {})["external_dirs"] = [f"{repo}/hermes/skills"] +cfg.setdefault("skills", {})["external_dirs"] = [f"{repo}/agent/skills"] cfg.setdefault("approvals", {})["mode"] = "smart" cfg_path.write_text(yaml.safe_dump(cfg, sort_keys=False)) print(f" config.yaml updated ({cfg_path})") PY # Persona -cp "$REPO_ROOT/hermes/SOUL.md" "$HERMES_HOME/SOUL.md" +cp "$REPO_ROOT/agent/SOUL.md" "$HERMES_HOME/SOUL.md" echo " SOUL.md installed" # Scope to a read-only sandbox: disable host-affecting toolsets. @@ -66,4 +69,4 @@ echo " SOUL.md installed" >/dev/null 2>&1 ) || echo " (toolset disable skipped — disable manually with 'hermes tools disable ...')" echo " host toolsets disabled (read-only deepsql + memory/todo/skills remain)" -echo "✓ DBA customization installed. Verify: (cd $AGENT_DIR && uv run hermes mcp test deepsql)" +echo "✓ DeepSQL Agent customization installed. Verify: (cd $AGENT_DIR && uv run hermes mcp test deepsql)" diff --git a/hermes/skills/bi-query/SKILL.md b/agent/skills/bi-query/SKILL.md similarity index 100% rename from hermes/skills/bi-query/SKILL.md rename to agent/skills/bi-query/SKILL.md diff --git a/hermes/skills/dashboard-design/SKILL.md b/agent/skills/dashboard-design/SKILL.md similarity index 100% rename from hermes/skills/dashboard-design/SKILL.md rename to agent/skills/dashboard-design/SKILL.md diff --git a/hermes/skills/index-advisor/SKILL.md b/agent/skills/index-advisor/SKILL.md similarity index 100% rename from hermes/skills/index-advisor/SKILL.md rename to agent/skills/index-advisor/SKILL.md diff --git a/hermes/skills/schema-exploration/SKILL.md b/agent/skills/schema-exploration/SKILL.md similarity index 100% rename from hermes/skills/schema-exploration/SKILL.md rename to agent/skills/schema-exploration/SKILL.md diff --git a/hermes/skills/slow-query-optimize/SKILL.md b/agent/skills/slow-query-optimize/SKILL.md similarity index 100% rename from hermes/skills/slow-query-optimize/SKILL.md rename to agent/skills/slow-query-optimize/SKILL.md diff --git a/hermes/skills/workload-analysis/SKILL.md b/agent/skills/workload-analysis/SKILL.md similarity index 100% rename from hermes/skills/workload-analysis/SKILL.md rename to agent/skills/workload-analysis/SKILL.md diff --git a/hermes/skins/deepsql.yaml b/agent/skins/deepsql.yaml similarity index 100% rename from hermes/skins/deepsql.yaml rename to agent/skins/deepsql.yaml diff --git a/hermes/tui/README.md b/agent/tui/README.md similarity index 90% rename from hermes/tui/README.md rename to agent/tui/README.md index 91ee930..69db06c 100644 --- a/hermes/tui/README.md +++ b/agent/tui/README.md @@ -2,9 +2,9 @@ The TUI's logo, hero art, and tagline live in the TUI **source** (`ui-tui/src/banner.ts`, `ui-tui/src/components/branding.tsx`) and its default -skin in `hermes_cli/skin_engine.py` — not in a skin YAML. So rebranding to -"DeepSQL Agent" means editing those files in the agent checkout and rebuilding -the Node/Ink dist (like `hermes/webui/apply-overlay.sh` for the webui). +skin in `hermes_cli/skin_engine.py` (upstream module path) — not in a skin YAML. +So rebranding to "DeepSQL Agent" means editing those files in the agent checkout +and rebuilding the Node/Ink dist (like `agent/webui/apply-overlay.sh` for the webui). Changing the *defaults* (not just our `deepsql` skin) also removes the brief flash of default branding at startup — there's no default left to render before @@ -61,7 +61,7 @@ const CADUCEUS_ART = [ ## Colors The wordmark color comes from the active skin's banner palette -([hermes/skins/deepsql.yaml](../skins/deepsql.yaml)) — kept in a tight grey +([agent/skins/deepsql.yaml](../skins/deepsql.yaml)) — kept in a tight grey range so it reads as a subtle, understated grey rather than bright white. ## Productization note diff --git a/hermes/tui/apply-branding.sh b/agent/tui/apply-branding.sh similarity index 95% rename from hermes/tui/apply-branding.sh rename to agent/tui/apply-branding.sh index 2f4a4ea..cf0a42b 100755 --- a/hermes/tui/apply-branding.sh +++ b/agent/tui/apply-branding.sh @@ -2,7 +2,7 @@ # Rebrand the TUI to "DeepSQL Agent" in an agent checkout, then rebuild the # Node/Ink dist. Idempotent. The TUI logo/tagline live in the TUI *source* # (not the skin), so this overlay edits them and rebuilds — vendored -# customization, applied like hermes/webui/apply-overlay.sh. +# customization, applied like agent/webui/apply-overlay.sh. # # Handles the clean string edits (tagline, default-skin branding) + rebuild. # The ASCII logo/hero blocks are in README.md (multi-line art doesn't sed @@ -40,7 +40,7 @@ fi if grep -q '\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x95\x97 \xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x95\x97\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x96\x88\xe2\x95\x97' "$BANNER"; then echo "= logo already DeepSQL wordmark" else - echo "! logo not yet replaced — paste the DeepSQL LOGO_ART + CADUCEUS_ART from hermes/tui/README.md into ui-tui/src/banner.ts" + echo "! logo not yet replaced — paste the DeepSQL LOGO_ART + CADUCEUS_ART from agent/tui/README.md into ui-tui/src/banner.ts" fi # 4. Rebuild the TUI dist. diff --git a/hermes/webui/README.md b/agent/webui/README.md similarity index 73% rename from hermes/webui/README.md rename to agent/webui/README.md index a2eca87..acb52fa 100644 --- a/hermes/webui/README.md +++ b/agent/webui/README.md @@ -1,20 +1,24 @@ -# DeepSQL Agent WebUI — DBA skin (Phase 2) +# DeepSQL Agent WebUI — DBA skin (optional overlay) -Source of truth for branding the agent webui (the web chat surface that replaces the React `AgentView`) to the DBA Agent design. +Source of truth for branding an upstream agent webui checkout to the DeepSQL DBA +look. The in-app Agent tab uses DeepSQL’s own React UI; this overlay is only for +operators who run the upstream webui directly. - `dba-skin.css` — a `data-skin="dba"` skin: minimal black/white/grey, Inter-first, flat surfaces, light + dark variants. Modeled on the built-in `graphite` skin. ## Install into a webui checkout -The webui is a separate cloned repo (default `~/.hermes/hermes-webui`). Apply the skin with the idempotent overlay script (safe to re-run, e.g. after re-pulling): +The webui is a separate cloned repo (default `~/.hermes/hermes-webui`, upstream +Nous Hermes Agent webui). Apply the skin with the idempotent overlay script +(safe to re-run, e.g. after re-pulling): ```bash -hermes/webui/apply-overlay.sh [path-to-webui] # default: ~/.hermes/hermes-webui +agent/webui/apply-overlay.sh [path-to-webui] # default: ~/.hermes/hermes-webui ``` It appends `dba-skin.css` to `static/style.css` and registers the skin in `static/boot.js` `_SKINS`, each guarded so re-runs are no-ops. Then reload the UI and select it: `/theme dba` then `/theme light` (or Settings → Appearance). -## Notes / follow-ups (Phase 2/3) +## Notes / follow-ups - **Vendoring:** these are edits to a cloned repo and will be lost on re-pull. Productization should maintain this as a patch/overlay applied at deploy (or fork the webui) so the repo stays source of truth. Pin matching webui ↔ agent release trains (the webui couples to the agent by direct import). - **Inter font:** the skin prefers `Inter` then falls back to system sans. For guaranteed Inter, bundle the webfont locally (don't depend on Google Fonts in a self-hosted deploy). diff --git a/hermes/webui/apply-overlay.sh b/agent/webui/apply-overlay.sh similarity index 98% rename from hermes/webui/apply-overlay.sh rename to agent/webui/apply-overlay.sh index 8f5d5bd..1f9bdf4 100755 --- a/hermes/webui/apply-overlay.sh +++ b/agent/webui/apply-overlay.sh @@ -4,6 +4,7 @@ # so the clone's files can be regenerated after a re-pull. # # Usage: ./apply-overlay.sh [path-to-webui] (default: ~/.hermes/hermes-webui) +# Default path is the upstream Hermes webui install location (HERMES_HOME contract). set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" diff --git a/hermes/webui/dba-skin.css b/agent/webui/dba-skin.css similarity index 98% rename from hermes/webui/dba-skin.css rename to agent/webui/dba-skin.css index 191aa32..20ea819 100644 --- a/hermes/webui/dba-skin.css +++ b/agent/webui/dba-skin.css @@ -2,7 +2,7 @@ * Minimal black/white/grey, Inter-first, flat surfaces (no shadows). * Matches the DBA Agent design language. Light + dark variants. * Install: append this file to the webui's static/style.css and register - * the skin in static/boot.js `_SKINS` (see hermes/webui/README.md). + * the skin in static/boot.js `_SKINS` (see agent/webui/README.md). */ :root[data-skin="dba"]{ diff --git a/backend/src/main/java/com/dbaagent/service/DashboardAgentService.java b/backend/src/main/java/com/dbaagent/service/DashboardAgentService.java index f8cba13..9c6dcca 100644 --- a/backend/src/main/java/com/dbaagent/service/DashboardAgentService.java +++ b/backend/src/main/java/com/dbaagent/service/DashboardAgentService.java @@ -17,7 +17,8 @@ import java.util.regex.Pattern; /** - * Dashboard generator — the embedded DeepSQL (Hermes) agent as a coding agent. + * Dashboard generator — the embedded DeepSQL Agent as a coding agent + * (customized Hermes runtime; see agent/README.md). * *

The agent doesn't fill in a rigid spec anymore. It writes the whole * dashboard as a single self-contained HTML document — any layout, filters, diff --git a/hermes/README.md b/hermes/README.md deleted file mode 100644 index 685abed..0000000 --- a/hermes/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# DeepSQL Agent customization - -Source of truth for the DeepSQL Agent customization layer. This directory contains -the DBA persona, skills, and deployment configuration for the self-hosted agent. - -## Contents - -- `SOUL.md` — the DBA persona / always-on system prompt. Encodes the DeepSQL grounding discipline (ground with `get_brain_context` before generating SQL, table-qualified columns, honor business rules + anti-patterns, read-only by default, two-step mutation confirm). -- `skills//SKILL.md` — procedural skills (agentskills.io format) loaded on demand: - - `bi-query` — answer a data question with grounded, read-only SQL - - `schema-exploration` — map/describe a database - - `index-advisor` — recommend (and dry-run/apply) indexes via the workload-weighted advisor - - `slow-query-optimize` — diagnose + rewrite one slow query - - `workload-analysis` — hotspots, regressions, per-customer load, growth - -These mirror the workflows the in-house `AgentOrchestrator` performed, re-expressed as agent persona + skills. - -## Install (local / self-host) - -Run the idempotent installer (requires the agent runtime already installed at `~/.hermes/hermes-agent`, and `AZURE_OPENAI_KEY` in the environment or the repo `.env`): - -```bash -hermes/install.sh -``` - -It configures `~/.hermes/config.yaml` reproducibly from this repo: -- **model** — Azure OpenAI gpt-5.4 via its OpenAI-compatible `…/openai/v1` endpoint (key read from env/.env, never committed) -- **mcp_servers.deepsql** — this repo's `mcp/deepsql-phase1-server.js` -- **skills.external_dirs** — this repo's `hermes/skills` (source of truth; must be a YAML list) -- **approvals.mode: smart**, **SOUL.md** persona, and disables host-affecting toolsets (terminal/file/code/browser/computer_use) → a read-only `deepsql:*` + memory/todo/skills sandbox - -Verify: -```bash -cd ~/.hermes/hermes-agent && uv run hermes mcp test deepsql # → ✓ Connected, 41 tools -``` - -The DeepSQL MCP server and the Spring backend remain the DBA brain; the agent consumes them. Web UI skin: see [`webui/`](webui/). - -### Approval UX (operator note) - -Because every exposed tool is read-only (`deepsql:*` reads; the one write tool, `apply_index_recommendation`, is server-side `confirm`-gated; host toolsets disabled), the webui per-call approval prompts add friction without adding safety for this deployment. Operators can enable the webui's session auto-approve (or per-tool "Always allow") so DBA turns flow without clicking. This is intentionally left as a deliberate operator action, not a baked-in default. diff --git a/src/lib/api/client.js b/src/lib/api/client.js index 5c8b7ad..d70424f 100644 --- a/src/lib/api/client.js +++ b/src/lib/api/client.js @@ -2609,7 +2609,8 @@ export const llmAPI = { }, }; -// Dashboard generation, delegated server-side to the embedded Hermes agent. The +// Dashboard generation, delegated server-side to the embedded DeepSQL Agent. +// (Customized Hermes runtime — see agent/README.md.) The // agent grounds on the brain + schema via MCP, writes each query, and verifies it // by running execute_sql and inspecting the rows (dates in-window, KPI value type // matches format, totals plausible) before emitting the spec. Returns diff --git a/src/lib/dashboardGenerator.js b/src/lib/dashboardGenerator.js index 4b716aa..3331396 100644 --- a/src/lib/dashboardGenerator.js +++ b/src/lib/dashboardGenerator.js @@ -1,6 +1,7 @@ import { dashboardGenAPI } from '@/lib/api/client' -// Dashboard generation runs the embedded Hermes agent as a CODING agent +// Dashboard generation runs the embedded DeepSQL Agent as a CODING agent +// (customized Hermes runtime — see agent/README.md). // (DashboardAgentService): it grounds on business rules + schema, verifies every // query with execute_sql, then writes the whole dashboard as a self-contained // HTML document — streaming its steps to the UI. The artifact renders in a