feat(hermes): support display.busy_input_mode + related knobs via HERMES_* env overlay #31

Open
opened 2026-08-31 11:15:41 +02:00 by hermes · 0 comments
Contributor

Feature: support display.busy_input_mode overlay via environment variable (and friends)

Goal

Allow stack operators to set the busy-input policy (display.busy_input_mode) — and ideally a small set of related display.* / agent.* / approvals.* knobs — through container environment: entries that compose into config.yaml on gateway startup, instead of forcing operators to edit config.yaml directly inside the persistent volume.

Why

admin/ansible#26 traced the “session interrupted by user message” symptom to display.busy_input_mode: interrupt (the default) in the prod gateway's config.yaml. The fix is a one-line config change, but applying it to a running gateway is fragile:

  • The config lives at $HERMES_HOME/config.yaml (today /opt/data/config.yaml), on a mounted volume that survives container restarts but does not propagate when brencher rolls a new compose.
  • The only built-in way to set the value is the /busy steer|queue|interrupt slash command — which is a per-session CLI operation, not a stack-deploy-time decision.
  • There is no environment-variable entry point for display.busy_input_mode (or related knobs) in the current Hermes 0.20.0 release (__release_date__ = "2026.8.3"). Verified by reading hermes_cli/__init__.py and hermes_cli/cli.py _handle_busy_command and grepping for busy_input_mode + getenv.

So once an operator runs /busy steer and writes the new value to config.yaml, the next brencher-stack-deploy that recreates the gateway container (e.g. when PR #27 healthcheck + stop_grace_period rolls) will silently lose the change unless someone hand-edits config.yaml again.

A real fix is: let the compose author declare the desired value in environment: and have the gateway image render that into config.yaml (or pass it through) at startup. This is the same pattern operators already use for HERMES_DASHBOARD_HOST, HERMES_YOLO_MODE, HTTP_PROXY, etc.

Proposed API

Each display.*, agent.*, approvals.*, memory.*, session_reset.* key that the gateway reads from config.yaml at startup gets an optional environment-variable override in the form:

HERMES_<SECTION>_<KEY> = <value>

Concretely:

Compose env Maps to config key
HERMES_DISPLAY_BUSY_INPUT_MODE display.busy_input_mode
HERMES_DISPLAY_SKIN display.skin
HERMES_DISPLAY_SHOW_REASONING display.show_reasoning
HERMES_AGENT_MAX_TURNS agent.max_turnns (clamped to existing internal bounds)
HERMES_MEMORY_CHAR_LIMIT memory.char_limit
HERMES_APPROVALS_MODE approvals.mode (smart/manual/off)
HERMES_SESSION_RESET_MODE session_reset.mode (none/both/...)
HERMES_MODEL_PROVIDER model.provider
HERMES_MODEL_DEFAULT model.default

Behavior:

  • Only set keys that already exist in the current config.yaml schema; unknown keys are ignored at startup with a one-time warning (operator typos show up in agent.log and gateway.log, never silently dropped).
  • Type coercion is the union of bool, int, float, str — same as the existing config loader. (true/false/1/0/yes/no accepted for booleans.)
  • Resolution order at each key lookup: explicit env var → explicit config.yaml value → built-in default (currently interrupt for busy_input_mode).
  • Per-key audit log: when an env override fires, log INFO config: <key> set from env HERMES_* (was <old value>, now <new value>). This makes stack-deploy audits trivial.
  • Read-only fallback when the config file is read-only: log a warning, do not crash the gateway. Container restarts should be best-effort, not fail.
  • .env-as-source-of-truth: documentation should recommend compose-level ENV as the new canonical way to set these knobs, with config.yaml reserved for advanced/local-only overrides.

Why now

  • admin/ansible#26 identified display.busy_input_mode as the upstream cause of the "бот престал отвечать" symptom. Once merged, PR #27 / #28 will roll the stack and silently reset the value unless an overlay exists.
  • Two hermes-gateway deploys now coexist in hermes_infra and docker_socket_proxy (per PR #29 docs/gateway-channels.md). Keeping their display.busy_input_mode aligned by default — via identical ENV — is the cheapest way to make them behave the same.

Out of scope (explicit)

  • Editing display.* from the gateway at runtime via slash commands — that already works.
  • A new section like display.env_overrides in config.yaml itself — would defeat the purpose of using compose-declared ENV as source of truth.
  • Per-session steering overrides for the Telegram platform adapter — separate ticket.

Test plan

  1. Add HERMES_DISPLAY_BUSY_INPUT_MODE=steer to the prod gateway compose (hermes_squid/stack-compose.yml).
  2. brencher-stack-deploy. Verify the freshly-launched gateway starts with display.busy_input_mode: steer in config.yaml (read via tar -xOf on /opt/data/config.yaml).
  3. Send a Telegram message in an active thread; expect the message to steer into the current run (no interruption), confirming behavior matches the configured mode.
  4. Roll the gateway again with the env var removed; expect config.yaml to fall back to the previous value (not to interrupt).
  5. Set HERMES_DISPLAY_BUSY_INPUT_MODE=typo; expect startup to log a warning and ignore the bad value rather than crashing.

References

  • Discovery: admin/ansible#26 (зацепка #5 — display.busy_input_mode: interrupt)
  • Hermes source: hermes_cli/__init__.py (declares __version__ = "0.20.0", __release_date__ = "2026.8.3") and hermes_cli/cli.py _handle_busy_command (only /busy slash-command path exists; no os.getenv for this key anywhere in hermes_cli/)
  • Diff that surfaced the gap: config.yaml between brencher-state-proxy removal-cycle compose and feat/docker-socket-proxy-readonly (see PR #26 thread for context)
## Feature: support `display.busy_input_mode` overlay via environment variable (and friends) ### Goal Allow stack operators to set the busy-input policy (`display.busy_input_mode`) — and ideally a small set of related `display.*` / `agent.*` / `approvals.*` knobs — through container `environment:` entries that compose into `config.yaml` on gateway startup, instead of forcing operators to edit `config.yaml` directly inside the persistent volume. ### Why `admin/ansible#26` traced the “session interrupted by user message” symptom to `display.busy_input_mode: interrupt` (the default) in the prod gateway's `config.yaml`. The fix is a one-line config change, but **applying it to a running gateway is fragile**: - The config lives at `$HERMES_HOME/config.yaml` (today `/opt/data/config.yaml`), on a mounted volume that survives container restarts but **does not propagate when brencher rolls a new compose**. - The only built-in way to set the value is the `/busy steer|queue|interrupt` slash command — which is a per-session CLI operation, not a stack-deploy-time decision. - There is **no environment-variable entry point** for `display.busy_input_mode` (or related knobs) in the current Hermes 0.20.0 release (`__release_date__ = "2026.8.3"`). Verified by reading `hermes_cli/__init__.py` and `hermes_cli/cli.py` `_handle_busy_command` and grepping for `busy_input_mode` + `getenv`. So once an operator runs `/busy steer` and writes the new value to `config.yaml`, the next brencher-stack-deploy that recreates the gateway container (e.g. when PR #27 healthcheck + stop_grace_period rolls) will **silently lose the change** unless someone hand-edits `config.yaml` again. A real fix is: **let the compose author declare the desired value in `environment:`** and have the gateway image render that into `config.yaml` (or pass it through) at startup. This is the same pattern operators already use for `HERMES_DASHBOARD_HOST`, `HERMES_YOLO_MODE`, `HTTP_PROXY`, etc. ### Proposed API Each `display.*`, `agent.*`, `approvals.*`, `memory.*`, `session_reset.*` key that the gateway reads from `config.yaml` at startup gets an optional **environment-variable override** in the form: ``` HERMES_<SECTION>_<KEY> = <value> ``` Concretely: | Compose env | Maps to config key | |---|---| | `HERMES_DISPLAY_BUSY_INPUT_MODE` | `display.busy_input_mode` | | `HERMES_DISPLAY_SKIN` | `display.skin` | | `HERMES_DISPLAY_SHOW_REASONING` | `display.show_reasoning` | | `HERMES_AGENT_MAX_TURNS` | `agent.max_turnns` (clamped to existing internal bounds) | | `HERMES_MEMORY_CHAR_LIMIT` | `memory.char_limit` | | `HERMES_APPROVALS_MODE` | `approvals.mode` (`smart`/`manual`/`off`) | | `HERMES_SESSION_RESET_MODE` | `session_reset.mode` (`none`/`both`/...) | | `HERMES_MODEL_PROVIDER` | `model.provider` | | `HERMES_MODEL_DEFAULT` | `model.default` | Behavior: - **Only set keys** that already exist in the current config.yaml schema; unknown keys are ignored at startup with a one-time warning (operator typos show up in `agent.log` and `gateway.log`, never silently dropped). - **Type coercion** is the union of `bool`, `int`, `float`, `str` — same as the existing config loader. (`true`/`false`/`1`/`0`/`yes`/`no` accepted for booleans.) - **Resolution order** at each key lookup: explicit env var → explicit `config.yaml` value → built-in default (currently `interrupt` for busy_input_mode). - **Per-key audit log**: when an env override fires, log `INFO config: <key> set from env HERMES_* (was <old value>, now <new value>)`. This makes stack-deploy audits trivial. - **Read-only fallback** when the config file is read-only: log a warning, do not crash the gateway. Container restarts should be best-effort, not fail. - **`.env-as-source-of-truth`**: documentation should recommend compose-level ENV as the new canonical way to set these knobs, with `config.yaml` reserved for advanced/local-only overrides. ### Why now - `admin/ansible#26` identified `display.busy_input_mode` as the upstream cause of the "бот престал отвечать" symptom. Once merged, PR #27 / #28 will roll the stack and **silently reset the value** unless an overlay exists. - Two `hermes-gateway` deploys now coexist in `hermes_infra` and `docker_socket_proxy` (per PR #29 docs/gateway-channels.md). Keeping their `display.busy_input_mode` aligned by default — via identical ENV — is the cheapest way to make them behave the same. ### Out of scope (explicit) - Editing `display.*` from the gateway at runtime via slash commands — that already works. - A new section like `display.env_overrides` in `config.yaml` itself — would defeat the purpose of using compose-declared ENV as source of truth. - Per-session steering overrides for the Telegram platform adapter — separate ticket. ### Test plan 1. Add `HERMES_DISPLAY_BUSY_INPUT_MODE=steer` to the prod gateway compose (`hermes_squid/stack-compose.yml`). 2. brencher-stack-deploy. Verify the freshly-launched gateway starts with `display.busy_input_mode: steer` in `config.yaml` (read via `tar -xOf` on `/opt/data/config.yaml`). 3. Send a Telegram message in an active thread; expect the message to **steer** into the current run (no interruption), confirming behavior matches the configured mode. 4. Roll the gateway again with the env var removed; expect `config.yaml` to fall back to the previous value (not to `interrupt`). 5. Set `HERMES_DISPLAY_BUSY_INPUT_MODE=typo`; expect startup to log a warning and ignore the bad value rather than crashing. ### References - Discovery: `admin/ansible#26` (зацепка #5 — `display.busy_input_mode: interrupt`) - Hermes source: `hermes_cli/__init__.py` (declares `__version__ = "0.20.0"`, `__release_date__ = "2026.8.3"`) and `hermes_cli/cli.py` `_handle_busy_command` (only `/busy slash`-command path exists; no `os.getenv` for this key anywhere in `hermes_cli/`) - Diff that surfaced the gap: config.yaml between `brencher-state-proxy` removal-cycle compose and `feat/docker-socket-proxy-readonly` (see PR #26 thread for context)
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: admin/ansible#31