Skip Hermes onboarding for managed agents (#46)

Author: JulioMCruz

CHANGELOG.md

@@ -9,6 +9,16 @@ versions are optional; date-stamped sections are fine for in-flight work.
 
 ## 2026-07-22
 
+### Managed Hermes first-message behavior
+
+PerkOS-managed Hermes agents now skip the upstream first-contact introduction
+and profile-building offer by default. A user's first channel message is
+answered directly, so requests such as “give me a short description” are not
+expanded with `/help` instructions or an unrelated profile prompt. The behavior
+is isolated behind `PERKOS_DISABLE_FIRST_MESSAGE_ONBOARDING=true` and can be
+overridden for self-hosted deployments. The image build applies a narrow,
+fail-fast runtime patch and stops if its upstream anchor changes.
+
 ### OpenClaw container healthcheck port alignment
 
 The OpenClaw image now exposes and probes port `3000`, matching the rendered

images/hermes/Dockerfile

@@ -44,14 +44,17 @@ RUN apt-get update && \
     rm -rf /var/lib/apt/lists/*
 
 COPY config/hermes.template.yaml /opt/perkos/hermes.template.yaml
+COPY patch-managed-runtime.py /opt/perkos/patch-managed-runtime.py
 COPY docker-entrypoint.sh /usr/local/bin/perkos-entrypoint.sh
 COPY snapshot.sh /usr/local/bin/perkos-snapshot.sh
 COPY restore.sh /usr/local/bin/perkos-restore.sh
 COPY perkos-render-profiles.py /usr/local/bin/perkos-render-profiles.py
 RUN chmod 755 /usr/local/bin/perkos-entrypoint.sh \
               /usr/local/bin/perkos-snapshot.sh \
               /usr/local/bin/perkos-restore.sh \
-              /usr/local/bin/perkos-render-profiles.py
+              /usr/local/bin/perkos-render-profiles.py && \
+    python3 /opt/perkos/patch-managed-runtime.py && \
+    python3 -m py_compile /opt/hermes/gateway/run.py
 
 # PerkOS Assistant content — SOUL (persona) + runbook (FAQ knowledge).
 # Used only when the container is provisioned as the platform identity
@@ -101,7 +104,8 @@ ENV PATH="/opt/hermes/.venv/bin:${PATH}"
 
 # Defaults — overridable at runtime via -e.
 ENV PERKOS_LLM_BASE_URL=https://api.llm.perkos.xyz/v1 \
-    PERKOS_LLM_DEFAULT_MODEL=kimi-k2.6:cloud
+    PERKOS_LLM_DEFAULT_MODEL=kimi-k2.6:cloud \
+    PERKOS_DISABLE_FIRST_MESSAGE_ONBOARDING=true
 
 # Our entrypoint runs FIRST (renders config, copies skill + platform
 # plugin into HERMES_HOME), then forks upstream's docker/entrypoint.sh

images/hermes/patch-managed-runtime.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Apply narrow, fail-fast PerkOS behavior patches to upstream Hermes."""
+
+from pathlib import Path
+
+
+GATEWAY_RUN = Path("/opt/hermes/gateway/run.py")
+FIRST_MESSAGE_GUARD = (
+    "if not history and not await self.async_session_store.has_any_sessions():"
+)
+MANAGED_FIRST_MESSAGE_GUARD = """if (
+            not _perkos_env_flag_disabled("PERKOS_DISABLE_FIRST_MESSAGE_ONBOARDING")
+            and not history
+            and not await self.async_session_store.has_any_sessions()
+        ):"""
+HELPER_ANCHOR = "logger = logging.getLogger(__name__)"
+HELPER = """
+
+def _perkos_env_flag_disabled(name: str) -> bool:
+    \"\"\"Return true when a PerkOS-managed upstream behavior is disabled.\"\"\"
+    return os.getenv(name, \"\").strip().lower() in {\"1\", \"true\", \"yes\", \"on\"}
+"""
+
+
+def replace_exactly_once(source: str, needle: str, replacement: str, label: str) -> str:
+    count = source.count(needle)
+    if count != 1:
+        raise RuntimeError(
+            f"{label}: expected exactly one upstream anchor, found {count}; "
+            "review the Hermes update before publishing this image"
+        )
+    return source.replace(needle, replacement, 1)
+
+
+source = GATEWAY_RUN.read_text(encoding="utf-8")
+source = replace_exactly_once(
+    source,
+    HELPER_ANCHOR,
+    HELPER_ANCHOR + HELPER,
+    "managed first-message helper",
+)
+source = replace_exactly_once(
+    source,
+    FIRST_MESSAGE_GUARD,
+    MANAGED_FIRST_MESSAGE_GUARD,
+    "managed first-message guard",
+)
+GATEWAY_RUN.write_text(source, encoding="utf-8")

tests/hermes/smoke.sh

@@ -247,6 +247,21 @@ else
   fail "config.yaml missing the PerkOS fast-response policy"
 fi
 
+if docker exec "$CONTAINER" sh -lc \
+    'test "$PERKOS_DISABLE_FIRST_MESSAGE_ONBOARDING" = true'; then
+  pass "managed agents disable upstream first-message onboarding by default"
+else
+  fail "managed first-message onboarding flag is not enabled"
+fi
+
+if docker exec "$CONTAINER" grep -q \
+    'not _perkos_env_flag_disabled("PERKOS_DISABLE_FIRST_MESSAGE_ONBOARDING")' \
+    /opt/hermes/gateway/run.py; then
+  pass "gateway source honors the managed first-message flag"
+else
+  fail "managed first-message runtime guard is missing"
+fi
+
 if echo "$config" | grep -A8 '^    telegram:' | grep -q "interim_assistant_messages: false"; then
   pass "telegram suppresses permanent interim assistant messages"
 else