@exulu/backend 1.63.2 → 1.64.0

package/ee/python/.hermes/.env.example

@@ -0,0 +1,8 @@
+# EXAMPLE ONLY — Exulu generates the real .env per profile at runtime (mode 0600).
+# Profile-local secrets referenced by ${VAR} in config.yaml.
+#
+# Runtime API-server params (API_SERVER_ENABLED / HOST / PORT / KEY) are NOT
+# stored here — the supervisor injects them via the child process environment so
+# port and key allocation stay owned by Exulu and a profile dir is portable.
+
+LITELLM_MASTER_KEY=replace-with-your-litellm-master-key

package/ee/python/.hermes/README.md

@@ -0,0 +1,44 @@
+# Hermes Agent profiles (advanced agent mode)
+
+This directory documents the per-profile files Exulu generates for the
+[Hermes Agent](https://hermes-agent.nousresearch.com) harness when an Exulu
+agent has **advanced mode** enabled. You do **not** edit anything here — Exulu's
+provisioner writes the real files at runtime under `${HERMES_HOME}/profiles/<id>/`.
+
+## How it fits together
+
+- One Hermes **profile** per Exulu agent (`<agentId>`), or per agent/user
+  (`<agentId>/<userId>`) when the agent's
+  `advanced_agent_profile_scope` is `private`.
+- Each in-use profile runs its own `hermes gateway` process on its own port,
+  supervised by `src/exulu/hermes/supervisor.ts` (lazy start + idle eviction).
+- Every model call still flows through the LiteLLM proxy — Hermes' `model`
+  block points `base_url` at LiteLLM.
+
+## Enabling
+
+1. `ENABLE_HERMES_AGENT=true` (gates install + the whole code path).
+2. Run `npm run python:setup` — installs the `hermes` binary when the flag is on.
+3. Toggle **advanced mode** on an individual agent in the agent form.
+
+## Env vars
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `ENABLE_HERMES_AGENT` | (unset) | Global gate for advanced mode. |
+| `HERMES_HOME` | `~/.hermes` | Root for profile directories. |
+| `HERMES_BIN` | (auto) | Override path to the `hermes` binary. |
+| `HERMES_PORT_RANGE` | `8642-8700` | Gateway port pool. |
+| `HERMES_MAX_GATEWAYS` | `20` | LRU cap on concurrent gateways. |
+| `HERMES_IDLE_TIMEOUT_MS` | `900000` | Idle eviction threshold (15 min). |
+| `HERMES_APPROVALS_MODE` | `smart` | Tool-approval policy written to config.yaml. |
+| `HERMES_TERMINAL_BACKEND` | `docker` | Backend that runs native shell/file tools (`docker` isolates without host user namespaces; `local`/`ssh`/`modal`/`daytona`/`singularity` also selectable). Docker must be available to the host process. |
+| `HERMES_DOCKER_IMAGE` | `nikolaik/python-nodejs:python3.11-nodejs20` | Image for the docker backend (needs python + node). |
+| `BACKEND` | `http://127.0.0.1:<PORT>` | URL a gateway uses to reach Exulu's `/mcp/:agentId` (set this if the host app's port isn't `PORT`/`EXULU_PORT`). |
+| `EXULU_MCP_KEY` | `LITELLM_MASTER_KEY` | Bearer token guarding the ExuluTools MCP endpoint. |
+
+ExuluTools reach the agent over HTTP MCP at `/mcp/<agentId>` and **add to** Hermes'
+native tools (bash, filesystem, …) rather than replacing them.
+
+See `config.yaml.example`, `.env.example`, and `SOUL.md.example` in this folder
+for the shape of the generated files.

package/ee/python/.hermes/SOUL.md.example

@@ -0,0 +1,8 @@
+<!-- EXAMPLE ONLY — Exulu generates the real SOUL.md per profile from the agent's
+     `instructions`. SOUL.md is slot #1 of the Hermes system prompt and defines
+     who the agent is. Exulu owns this file and rewrites it whenever the agent's
+     instructions change (Hermes never overwrites an existing SOUL.md). -->
+
+You are Acme Corp's research assistant. You are precise, cite your sources, and
+prefer primary documents over summaries. When unsure, you say so rather than
+guessing.

package/ee/python/.hermes/config.yaml.example

@@ -0,0 +1,55 @@
+# EXAMPLE ONLY — Exulu generates the real config.yaml per profile at runtime.
+# Documentation: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
+#
+# The model block points Hermes at the LiteLLM proxy so every model call still
+# flows through the single model gateway. NOTE: the model-name key is `default`,
+# not `model`. When base_url is set, Hermes calls it directly using api_key.
+
+model:
+  default: "claude-haiku"            # a LiteLLM model_name from config.litellm.yaml
+  provider: custom
+  base_url: "http://127.0.0.1:4000/v1"
+  api_key: "${LITELLM_MASTER_KEY}"  # resolved from the profile .env / process env
+  api_mode: chat_completions
+
+# Tool-approval policy: `smart` auto-approves low-risk actions and emits an
+# approval event (requiring a decision) before destructive ones.
+approvals:
+  mode: smart
+
+# Native shell/file tools run via this backend. Default is `docker`: a hardened,
+# Hermes-managed container (cap-drop ALL, no-new-privileges) that isolates the
+# tools from the host WITHOUT needing user namespaces — so it behaves the same
+# on macOS (Docker Desktop) and Linux. Volumes are bind-mounted host->same path
+# so the absolute cwd / skills.external_dirs resolve inside the container;
+# secrets are not mounted. Set HERMES_TERMINAL_BACKEND=local to disable.
+terminal:
+  backend: docker
+  # No bind mount: the Files panel talks to the container's /root directly via
+  # docker exec/cp. We stamp a deterministic label so Exulu can find the
+  # container (docker ps --filter label=exulu-profile=<profileId>), and keep it
+  # persistent so files survive between runs.
+  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
+  container_persistent: true
+  lifetime_seconds: 86400
+  # Run as root (home /root) so the agent's working dir is a predictable /root
+  # the Files panel reads — NOT the host user's home (e.g. /Users/<you>), which
+  # is what docker_run_as_host_user (default) would replicate.
+  docker_run_as_host_user: false
+  docker_mount_cwd_to_workspace: false
+  docker_extra_args: ["--label", "exulu-profile=<profileId>"]
+    - "/abs/.../profiles/<profileId>/exulu-skills:/abs/.../profiles/<profileId>/exulu-skills:ro"
+
+# Added in Phase 3 — ExuluTools exposed over HTTP MCP at /mcp/<agentId>:
+# mcp_servers:
+#   exulu:
+#     url: "http://127.0.0.1:<exulu-port>/mcp/<agentId>"
+#     headers:
+#       Authorization: "Bearer ${EXULU_MCP_KEY}"
+
+# Enabled Exulu skills, synced from S3 into the profile (Anthropic Agent Skills
+# format). ADDS to Hermes' own skills home (learned/bundled skills); only
+# written when the agent has skills enabled.
+# skills:
+#   external_dirs:
+#     - "/abs/path/to/${HERMES_HOME}/profiles/<profileId>/exulu-skills"

package/ee/python/setup.sh

@@ -253,6 +253,46 @@ if [ -n "$LITELLM_PROXY_DIR" ] && [ -f "$LITELLM_PROXY_DIR/schema.prisma" ]; the
         || print_warning "Prisma generate failed; LiteLLM database mode (database_url in config.litellm.yaml) may not work until you run 'cd $LITELLM_PROXY_DIR && PATH=$VENV_DIR/bin:\$PATH $VENV_DIR/bin/prisma generate'"
 fi
 
+# Step 6.6: Install the Hermes Agent harness (advanced agent mode).
+# Opt-in via ENABLE_HERMES_AGENT=true. Hermes is NOT a pip package — it ships
+# as a standalone binary via Nous Research's official installer (lands in
+# ~/.local/bin/hermes). We only install if it's not already present so re-runs
+# are fast, and we never fail the whole setup if the install fails (advanced
+# mode is optional; the operator can install it manually and retry).
+if [ "${ENABLE_HERMES_AGENT}" = "true" ]; then
+    echo ""
+    echo "Step 6.6: Installing Hermes Agent harness (ENABLE_HERMES_AGENT=true)..."
+    if command -v hermes &> /dev/null || [ -x "$HOME/.local/bin/hermes" ]; then
+        HERMES_VERSION=$( (command -v hermes &> /dev/null && hermes --version 2>/dev/null) || "$HOME/.local/bin/hermes" --version 2>/dev/null || echo "unknown")
+        print_success "Hermes already installed ($HERMES_VERSION) — skipping installer"
+    else
+        print_info "Running Hermes official installer..."
+        if curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash; then
+            print_success "Hermes Agent installed (binary at ~/.local/bin/hermes)"
+        else
+            print_warning "Hermes installer failed. Advanced agent mode will be unavailable until 'hermes' is on PATH. Install manually: https://hermes-agent.nousresearch.com/docs/getting-started/installation"
+        fi
+    fi
+
+    # Pre-pull the docker terminal-backend image so the first agent request
+    # isn't blocked on a cold image pull (~minute). Only when the backend is
+    # docker (the default) and docker is available; non-fatal otherwise.
+    HERMES_BACKEND="${HERMES_TERMINAL_BACKEND:-docker}"
+    if [ "${HERMES_BACKEND}" = "docker" ]; then
+        HERMES_IMG="${HERMES_DOCKER_IMAGE:-nikolaik/python-nodejs:python3.11-nodejs20}"
+        if command -v docker &> /dev/null; then
+            print_info "Pre-pulling Hermes docker backend image: ${HERMES_IMG}..."
+            if docker pull "${HERMES_IMG}" > /dev/null 2>&1; then
+                print_success "Docker backend image ready (${HERMES_IMG})"
+            else
+                print_warning "Could not pre-pull ${HERMES_IMG}; the first advanced-mode request will pull it (slower)."
+            fi
+        else
+            print_warning "Docker not found, but HERMES_TERMINAL_BACKEND=docker. Install Docker, or set HERMES_TERMINAL_BACKEND=local (unsandboxed)."
+        fi
+    fi
+fi
+
 # Step 7: Validate installation
 echo ""
 echo "Step 7: Validating installation..."
@@ -269,6 +309,15 @@ $PYTHON_CMD -c "import whisperx" 2>/dev/null && print_success "whisperx imported
 $PYTHON_CMD -c "import pyannote.audio" 2>/dev/null && print_success "pyannote.audio imported successfully" || print_warning "pyannote.audio not importable (diarization will be disabled even with HF_AUTH_TOKEN)"
 $PYTHON_CMD -c "import fastapi, uvicorn" 2>/dev/null && print_success "fastapi/uvicorn imported successfully" || print_warning "fastapi/uvicorn not importable (transcription server will not start)"
 
+# Hermes Agent binary check (advanced agent mode) — only when opted in.
+if [ "${ENABLE_HERMES_AGENT}" = "true" ]; then
+    if command -v hermes &> /dev/null || [ -x "$HOME/.local/bin/hermes" ]; then
+        print_success "hermes binary available (advanced agent mode ready)"
+    else
+        print_warning "hermes binary not found (advanced agent mode will be unavailable)"
+    fi
+fi
+
 # Step 8: Display summary
 echo ""
 echo -e "${GREEN}========================================${NC}"

package/ee/schemas.ts

@@ -73,6 +73,10 @@ export const rolesSchema: ExuluTableDefinition = {
             name: "evals",
             type: "text", // write | read access to evals
         },
+        {
+            name: "budget_management",
+            type: "text", // write | read access to budgets
+        },
     ],
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exulu/backend",
   "author": "Qventu Bv.",
-  "version": "1.63.2",
+  "version": "1.64.0",
   "main": "./dist/index.js",
   "private": false,
   "publishConfig": {