fix(hermes): harden messaging onboarding

Author: shannonsands

agents/hermes/Dockerfile

@@ -101,6 +101,7 @@ ARG NEMOCLAW_INFERENCE_API=openai-completions
 ARG CHAT_UI_URL=http://127.0.0.1:8642
 ARG NEMOCLAW_MESSAGING_CHANNELS_B64=W10=
 ARG NEMOCLAW_MESSAGING_ALLOWED_IDS_B64=e30=
+ARG NEMOCLAW_DISCORD_GUILDS_B64=e30=
 ARG NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS_B64=W10=
 ARG NEMOCLAW_HERMES_TOOL_GATEWAY_BROKER=0
 ARG NEMOCLAW_BUILD_ID=default
@@ -114,6 +115,7 @@ ENV NEMOCLAW_MODEL=${NEMOCLAW_MODEL} \
     CHAT_UI_URL=${CHAT_UI_URL} \
     NEMOCLAW_MESSAGING_CHANNELS_B64=${NEMOCLAW_MESSAGING_CHANNELS_B64} \
     NEMOCLAW_MESSAGING_ALLOWED_IDS_B64=${NEMOCLAW_MESSAGING_ALLOWED_IDS_B64} \
+    NEMOCLAW_DISCORD_GUILDS_B64=${NEMOCLAW_DISCORD_GUILDS_B64} \
     NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS_B64=${NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS_B64} \
     NEMOCLAW_HERMES_TOOL_GATEWAY_BROKER=${NEMOCLAW_HERMES_TOOL_GATEWAY_BROKER}
 

agents/hermes/generate-config.ts

@@ -24,6 +24,10 @@ const TOKEN_ENV: Record<string, string> = {
   slack: "SLACK_BOT_TOKEN",
 };
 
+const APP_TOKEN_ENV: Record<string, string> = {
+  slack: "SLACK_APP_TOKEN",
+};
+
 const ALLOWED_USERS_ENV: Record<string, string> = {
   telegram: "TELEGRAM_ALLOWED_USERS",
   discord: "DISCORD_ALLOWED_USERS",
@@ -60,6 +64,14 @@ type ToolGatewayMatrixEntry = {
 
 type ToolGatewayMatrix = Record<string, ToolGatewayMatrixEntry>;
 
+type DiscordGuildConfig = Record<
+  string,
+  {
+    requireMention?: boolean;
+    users?: string[];
+  }
+>;
+
 function loadToolGatewayMatrix(): ToolGatewayMatrix {
   const scriptDir = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -127,6 +139,44 @@ function parseToolGatewayPresets(): string[] {
   });
 }
 
+function parseDiscordGuilds(): DiscordGuildConfig {
+  const raw = process.env.NEMOCLAW_DISCORD_GUILDS_B64 || "e30=";
+  try {
+    const parsed = JSON.parse(Buffer.from(raw, "base64").toString("utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed as DiscordGuildConfig;
+  } catch {
+    return {};
+  }
+}
+
+function discordAllowedUsers(
+  allowedIds: Record<string, (string | number)[]>,
+  discordGuilds: DiscordGuildConfig,
+): string[] {
+  const users = new Set<string>();
+  for (const id of allowedIds.discord ?? []) {
+    const value = String(id).trim();
+    if (value) users.add(value);
+  }
+  for (const guild of Object.values(discordGuilds)) {
+    if (!Array.isArray(guild.users)) continue;
+    for (const user of guild.users) {
+      const value = String(user).trim();
+      if (value) users.add(value);
+    }
+  }
+  return [...users];
+}
+
+function discordRequireMention(discordGuilds: DiscordGuildConfig): boolean | null {
+  const configured = Object.values(discordGuilds)
+    .map((guild) => guild.requireMention)
+    .filter((value): value is boolean => typeof value === "boolean");
+  if (configured.length === 0) return null;
+  return configured.every(Boolean);
+}
+
 function main(): void {
   const model = process.env.NEMOCLAW_MODEL!;
   const baseUrl = process.env.NEMOCLAW_INFERENCE_BASE_URL!;
@@ -139,6 +189,7 @@ function main(): void {
   const allowedIds: Record<string, (string | number)[]> = JSON.parse(
     Buffer.from(allowedIdsB64, "base64").toString("utf-8"),
   );
+  const discordGuilds = parseDiscordGuilds();
   const toolGatewayPresets = parseToolGatewayPresets();
   const toolGatewayBrokerEnabled =
     toolGatewayPresets.length > 0 || process.env.NEMOCLAW_HERMES_TOOL_GATEWAY_BROKER === "1";
@@ -223,6 +274,18 @@ function main(): void {
           allowed_users: allowedIds[ch].map(String).join(","),
         };
       }
+      if (ch === "discord") {
+        const users = discordAllowedUsers(allowedIds, discordGuilds);
+        const requireMention = discordRequireMention(discordGuilds);
+        const extra = {
+          ...((pCfg.extra as Record<string, unknown> | undefined) ?? {}),
+          ...(users.length > 0 ? { allowed_users: users.join(",") } : {}),
+          ...(requireMention !== null ? { require_mention: requireMention } : {}),
+        };
+        if (Object.keys(extra).length > 0) {
+          pCfg.extra = extra;
+        }
+      }
       platformsConfig[ch] = pCfg;
     }
   }
@@ -281,7 +344,10 @@ function main(): void {
     if (ch in TOKEN_ENV) {
       envLines.push(`${TOKEN_ENV[ch]}=openshell:resolve:env:${TOKEN_ENV[ch]}`);
     }
-    if (ch in ALLOWED_USERS_ENV && allowedIds[ch]?.length) {
+    if (ch in APP_TOKEN_ENV) {
+      envLines.push(`${APP_TOKEN_ENV[ch]}=openshell:resolve:env:${APP_TOKEN_ENV[ch]}`);
+    }
+    if (ch !== "discord" && ch in ALLOWED_USERS_ENV && allowedIds[ch]?.length) {
       const allowed = allowedIds[ch].map(String).join(",");
       envLines.push(`${ALLOWED_USERS_ENV[ch]}=${allowed}`);
       if (ch === "telegram") {
@@ -290,6 +356,14 @@ function main(): void {
         envLines.push("TELEGRAM_HOME_CHANNEL_NAME=NemoHermes DM");
       }
     }
+    if (ch === "discord") {
+      const allowed = discordAllowedUsers(allowedIds, discordGuilds).join(",");
+      if (allowed) envLines.push(`DISCORD_ALLOWED_USERS=${allowed}`);
+      const requireMention = discordRequireMention(discordGuilds);
+      if (requireMention !== null) {
+        envLines.push(`DISCORD_REQUIRE_MENTION=${requireMention ? "1" : "0"}`);
+      }
+    }
   }
 
   const envPath = join(homedir(), ".hermes", ".env");

agents/hermes/plugin/__init__.py

@@ -3,15 +3,22 @@
 """
 NemoClaw plugin for Hermes Agent.
 
-Provides sandbox status tools and skill hot-reload when Hermes runs inside an
-OpenShell sandbox managed by NemoClaw.
+Provides sandbox status tools, skill hot-reload, managed-tool broker patches,
+and quiet runtime grounding when Hermes runs inside an OpenShell sandbox
+managed by NemoClaw.
 
 Skill hot-reload: Hermes caches its skill slash-command registry in a
 module-global dict on first scan. New skills dropped on disk are invisible
 until the cache is cleared. This plugin provides a nemoclaw_reload_skills
 tool that clears the cache and re-scans, letting the agent pick up new
 skills without a gateway restart. The on_session_start hook also refreshes
 skills automatically at session boundaries.
+
+Runtime grounding: earlier versions injected a visible startup banner, but
+Hermes TUI renders plugin-injected messages through the interrupt queue. This
+plugin now uses Hermes' pre_llm_call context hook so the model sees the
+NemoClaw sandbox/tool-execution topology without leaking visual noise into the
+chat transcript.
 """
 
 import atexit
@@ -41,6 +48,28 @@
     "modal": "MODAL_GATEWAY_URL",
 }
 
+_NEMOCLAW_CONTEXT_KEYWORDS = (
+    "browser",
+    "config",
+    "discord",
+    "environment",
+    "gateway",
+    "hermes",
+    "host",
+    "logs",
+    "modal",
+    "nemoclaw",
+    "openshell",
+    "sandbox",
+    "skill",
+    "slack",
+    "status",
+    "telegram",
+    "tool",
+    "where am i",
+    "whoami",
+)
+
 
 def _get_env_value(key, default=None):
     """Read env from os.environ, then Hermes' dotenv-aware config loader."""
@@ -858,6 +887,81 @@ def _get_sandbox_info():
     }
 
 
+def _active_managed_gateway_services():
+    """List managed Nous services that have broker URLs configured."""
+    services = []
+    for service, env_key in _TOOL_GATEWAY_URL_ENV.items():
+        if _get_env_value(env_key, ""):
+            services.append(service)
+    return services
+
+
+def _should_inject_nemoclaw_context(user_message=None, is_first_turn=False):
+    """Return whether this turn needs NemoClaw runtime grounding."""
+    if is_first_turn:
+        return True
+    text = str(user_message or "").lower()
+    return any(keyword in text for keyword in _NEMOCLAW_CONTEXT_KEYWORDS)
+
+
+def _build_nemoclaw_agent_context(platform=None):
+    """Build quiet, ephemeral context for Hermes' pre_llm_call hook."""
+    info = _get_sandbox_info()
+    hermes_home = (
+        os.getenv("HERMES_HOME")
+        or _get_env_value("HERMES_HOME", "")
+        or "/sandbox/.hermes-data"
+    )
+    services = _active_managed_gateway_services()
+    service_text = ", ".join(services) if services else "none detected"
+    broker_state = "enabled" if _broker_mode_enabled() else "not enabled"
+    platform_text = str(platform or "").strip()
+    platform_line = (
+        f"- Current Hermes messaging platform: {platform_text}. Messaging adapters "
+        "run in the parent Hermes gateway sandbox; child tool-execution containers "
+        "will not show their host/gateway config."
+        if platform_text
+        else "- Messaging adapters run in the parent Hermes gateway sandbox; child "
+        "tool-execution containers will not show their host/gateway config."
+    )
+
+    return "\n".join(
+        [
+            "NemoClaw runtime context:",
+            "- You are Hermes Agent running in a NemoClaw-managed OpenShell sandbox, "
+            "not a host-only assistant.",
+            "- Some tools, especially managed code/terminal tools, execute in child "
+            "tool sandboxes such as Modal. Seeing /__modal, MODAL_SANDBOX_ID, a "
+            "missing hermes binary, or missing ~/.hermes-data inside a tool shell "
+            "means that shell is a child tool sandbox, not proof that Hermes is "
+            "running on the host.",
+            f"- Parent Hermes sandbox config lives under {hermes_home} and "
+            "/sandbox/.hermes when available. Use nemoclaw_status or "
+            "nemoclaw_info for NemoClaw environment questions.",
+            f"- NemoClaw provider state: model={info['model']}, "
+            f"provider={info['provider']}, endpoint={info['base_url']}, "
+            f"gateway={info['gateway']}.",
+            "- NemoClaw tools available: nemoclaw_status, nemoclaw_info, "
+            "nemoclaw_reload_skills, transcribe_audio.",
+            f"- Managed Nous tool broker: {broker_state}; configured services: "
+            f"{service_text}. Raw Nous OAuth tokens are host-managed by NemoClaw "
+            "and should not be expected inside the sandbox.",
+            platform_line,
+        ],
+    )
+
+
+def _pre_llm_call(**kwargs):
+    """Inject non-visible NemoClaw runtime context into relevant Hermes turns."""
+    if not _should_inject_nemoclaw_context(
+        user_message=kwargs.get("user_message"),
+        is_first_turn=bool(kwargs.get("is_first_turn")),
+    ):
+        return None
+    _install_nous_tool_broker_patch()
+    return {"context": _build_nemoclaw_agent_context(platform=kwargs.get("platform"))}
+
+
 def _handle_status(tool_input=None, context=None, **_kwargs):
     """Handle the nemoclaw_status tool call."""
     info = _get_sandbox_info()
@@ -1043,6 +1147,10 @@ def register(ctx):
         description="Reload skills from disk without gateway restart",
     )
 
+    # Ground the model quietly through Hermes' context hook. This replaces the
+    # old visible startup banner without reintroducing TUI interrupt noise.
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+
     # Refresh skills silently on session start. Earlier versions injected a
     # system banner here, but that can interrupt the user's first prompt in the
     # Hermes TUI because plugin-injected messages travel through Hermes's

nemoclaw-blueprint/policies/presets/discord.yaml

@@ -44,5 +44,10 @@ network_policies:
         rules:
           - allow: { method: GET, path: "/**" }
     binaries:
+      - { path: /usr/local/bin/hermes }
+      - { path: /usr/bin/python3 }
+      - { path: /usr/bin/python3.11 }
+      - { path: /usr/local/bin/python3 }
+      - { path: /usr/local/bin/python3.11 }
       - { path: /usr/local/bin/node }
       - { path: /usr/bin/node }

nemoclaw-blueprint/policies/presets/slack.yaml

@@ -43,5 +43,10 @@ network_policies:
         access: full
         tls: skip
     binaries:
+      - { path: /usr/local/bin/hermes }
+      - { path: /usr/bin/python3 }
+      - { path: /usr/bin/python3.11 }
+      - { path: /usr/local/bin/python3 }
+      - { path: /usr/local/bin/python3.11 }
       - { path: /usr/local/bin/node }
       - { path: /usr/bin/node }

nemoclaw-blueprint/policies/presets/telegram.yaml

@@ -19,5 +19,10 @@ network_policies:
           - allow: { method: POST, path: "/bot*/**" }
           - allow: { method: GET, path: "/file/bot*/**" }
     binaries:
+      - { path: /usr/local/bin/hermes }
+      - { path: /usr/bin/python3 }
+      - { path: /usr/bin/python3.11 }
+      - { path: /usr/local/bin/python3 }
+      - { path: /usr/local/bin/python3.11 }
       - { path: /usr/local/bin/node }
       - { path: /usr/bin/node }