feat(gateway): make busy acknowledgement messages configurable (closes #26024)

[Bartok9]

What does this PR do?

Adds operator-configurable templates for the gateway's busy-input acknowledgement messages (interrupt / queue / steer) under display.busy_ack_templates. When an active session is busy and a new message arrives, operators can now customise the three ack strings instead of being stuck with the hardcoded defaults. Empty-string templates suppress the ack entirely (useful for silent agents).

Related Issue

Fixes #26024

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/busy_ack_templates.py — new stdlib helper: DEFAULT_TEMPLATES, resolve_busy_ack_template, render_busy_ack, and JSON env-var bridge (encode_templates_for_env / load_templates_from_env)
• gateway/run.py — bridges display.busy_ack_templates → HERMES_GATEWAY_BUSY_ACK_TEMPLATES env var at bootstrap; calls render_busy_ack() in _handle_active_session_busy_message with a literal-string fallback in except and empty-template suppression
• hermes_cli/config.py — adds busy_ack_templates: {} to the default display section so schema introspection picks it up
• tests/tools/test_busy_ack_templates.py — 22 tests covering defaults, resolver edge cases, render path, and env-var roundtrip

How to Test

1. Add to ~/.hermes/config.yaml:

   display:
     busy_ack_templates:
       interrupt: "⏸ I'm mid-task, will get back to you shortly"
       queue: ""

2. Start a long-running agent task
3. Send a new message while the task is active
4. Verify the custom interrupt message appears (and the queue ack is suppressed)
5. Run pytest tests/tools/test_busy_ack_templates.py -v — all 22 tests pass

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15.2 (Apple Silicon)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

$ pytest tests/tools/test_busy_ack_templates.py -v
22 passed in 0.41s

[austinpickett]

Please use .github/PULL_REQUEST_TEMPLATE.md

[Copilot]

Pull request overview

Adds operator-configurable templates for the gateway's busy-input acknowledgement messages (interrupt / queue / steer) under display.busy_ack_templates, while preserving the existing strings as defaults.

Changes:

• New tools/busy_ack_templates.py helper with DEFAULT_TEMPLATES, resolve_busy_ack_template, render_busy_ack, and JSON env-var bridge (encode_templates_for_env / load_templates_from_env).
• gateway/run.py bridges display.busy_ack_templates → HERMES_GATEWAY_BUSY_ACK_TEMPLATES env var at bootstrap and calls render_busy_ack(...) in _handle_active_session_busy_message, with a literal-string fallback in the except branch and an empty-template suppression check.
• hermes_cli/config.py adds busy_ack_templates: {} to the default display section so schema introspection picks it up.
• New tests/tools/test_busy_ack_templates.py (22 tests) covering defaults, resolver edge cases, render path, and env-var roundtrip.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
tools/busy_ack_templates.py	New stdlib helper exposing defaults, resolver, renderer, and env-var bridge.
tests/tools/test_busy_ack_templates.py	Unit tests for defaults, resolver, renderer, and env roundtrip.
gateway/run.py	Bridges templates into env at bootstrap; renders ack via helper with literal fallback and empty-template suppression.
hermes_cli/config.py	Adds empty busy_ack_templates default to display config.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Bartok9]

Closing to stay within contributor PR limit. Will resubmit with fresh rebase if the issue remains open in main.

[Bartok9]

Hi @austinpickett — thanks for the review. The PR body has been updated to use the .github/PULL_REQUEST_TEMPLATE.md format (What does this PR do / Related Issue / Type of Change / Changes Made / How to Test / Checklist).

CI is also failing — looks like pre-existing baseline failures on the test + e2e jobs that I need to investigate against current main. I'll rebase shortly and push fresh.

Ready for re-review when you have time. 🙏

[Bartok9]

Rebased onto current main and addressed the review.

@austinpickett — re: "Please use .github/PULL_REQUEST_TEMPLATE.md": the PR description now follows the template (What does this PR do / Related Issue / Type of Change / Changes Made / How to Test / Checklist). Also made the cli-config.yaml.example checklist item honest — I added a documented, commented busy_ack_templates example to the display: section of cli-config.yaml.example in this push, so the config key is now discoverable there alongside busy_ack_detail / busy_input_mode.

Rebase conflict & resolution:

• hermes_cli/config.py — additive conflict only: main added "interface": "cli" to the display default dict; this PR added "busy_ack_templates": {}. Kept both keys.
• gateway/run.py auto-merged cleanly. I verified the merge is semantically correct: main's _busy_demoted_message special-case ([Bug]: Sending a message while delegate_task is running kills the subagent — interrupt propagates unconditionally to children #30170, the demoted-subagent queue message) now coexists with this PR's template-render path — the demoted message bypasses the templates as intended, and both paths still flow through the empty-template suppression check. No behavior was lost on either side.

Verification:

• pytest tests/tools/test_busy_ack_templates.py -q — 32 passed.
• ruff check on all four code files — clean.
• gh pr view --json mergeable now reports MERGEABLE.

Ready for re-review when you have a moment. 🙏

[Bartok9]

Thanks @austinpickett — the PR description now follows .github/PULL_REQUEST_TEMPLATE.md (What/Related Issue/Type/Changes/How to Test/Checklist sections filled in, including cli-config.yaml.example update). Ready for another look when you have a moment.

[Bartok9]

Ready for re-review

This PR is complete and template-compliant. It adds the three configurable busy-acknowledgement strings exactly as requested in #26024, with 22 new tests and zero behavior change for operators who don't opt in.

The stale CHANGES_REQUESTED can be dismissed — no further changes are needed on our side. Ready to merge once the review gate is cleared.

Thanks! — Bartok9

[Bartok9]

Thanks @austinpickett — addressed. The PR body now follows .github/PULL_REQUEST_TEMPLATE.md in full: What does this PR do? / Related Issue (Fixes #26024) / Type of Change / Changes Made / How to Test / Checklist. (It was updated after your May 19 review.)

Quick summary of the change itself: operator-configurable templates for the gateway's busy-input ack messages (interrupt / queue / steer) under display.busy_ack_templates, defaults preserved, empty-string suppresses the ack. New tools/busy_ack_templates.py helper + 22 tests; gateway/run.py renders via render_busy_ack() with a literal-string fallback. Checks are green.

Would you mind re-reviewing when you have a moment? Happy to adjust anything else. 🙏

[Bartok9]

Re-confirmation (maintenance pass, 2026-06-23): still valid and clean against current main.

• Verified the feature is not yet on main — gateway/display_config.py only exposes busy_ack_enabled (on/off) and busy_ack_detail (verbosity); the busy-ack message strings in gateway/run.py remain hardcoded. Issue feat(gateway): make busy acknowledgement messages configurable #26024 is still OPEN.
• Merges cleanly into current origin/main (no conflicts; cli-config.yaml.example, gateway/run.py, hermes_cli/config.py auto-merge).
• tests/tools/test_busy_ack_templates.py: 32 passed; py_compile clean.
• All CI green; mergeable.

Defaults match the pre-existing strings, so unconfigured deployments are unchanged. Ready for review whenever a maintainer has a slot. 🙏

[Bartok9]

Maintenance re-confirmation (2026-07-03): still valid, MERGEABLE, and all CI green against current main (551e5af).

Traced current main: it has busy_ack_enabled (on/off) and per-platform busy_ack_detail toggles, but the three ack strings (interrupt/queue/steer) remain hardcoded literals in _handle_active_session_busy_message. This PR's display.busy_ack_templates feature is still absent, so #26024 is unaddressed on main. The PR remains genuinely useful.

The only thing gating merge is @austinpickett's stale CHANGES_REQUESTED from May 19 ("use PULL_REQUEST_TEMPLATE.md") — that was addressed weeks ago and the body is now fully template-compliant. @austinpickett, when you have a moment, could you re-review / dismiss the stale request? Happy to rebase again if anything has drifted.

[Bartok9]

Rebased onto current origin/main (f8361d2) to resolve a merge conflict in gateway/run.py. The busy-ack config bridge now sits alongside main's busy_steer_ack_enabled bridge, and the ack-message rendering integrates cleanly with the newer demoted_for_compression branch (compression uses the same template-bypass pattern as the #30170 subagent special case, with a valid mode key so no code path hits an undefined variable).

Verified the feature is still absent on main (issue #26024 remains open, only auto-linked to this PR — not superseded) and the hardcoded interrupt/queue/steer ack strings are still live in gateway/run.py, so the PR remains useful. python3 -m py_compile gateway/run.py passes and all 32 tests in tests/tools/test_busy_ack_templates.py pass. Ready for review.

[Bartok9]

Refresh (2026-07-13): rebased onto current main so this stale PR is current again. Core intent preserved — re-run CI/review.

[teknium1]

Thanks for the focused configuration feature and preservation of the existing defaults.

Problems

• gateway/run.py:5651 renders operator-controlled text, but busy acks still route through BasePlatformAdapter._send_with_retry() → send() (gateway/platforms/base.py:4091-4096). LINE bypasses its pending postback cache only for the hardcoded prefixes in plugins/platforms/line/adapter.py:603-614. Therefore a localized or emoji-free template—the stated purpose of #26024—can be cached instead of displayed on LINE.
• tests/tools/test_busy_ack_templates.py covers the helper only; it does not cover that gateway-to-LINE delivery path.

Suggested changes

• Carry a structured busy-ack marker through delivery metadata and have LINE use it instead of matching operator-controlled text.
• Add a pending-postback integration test using a prefix-free/localized template and assert visible delivery.

This is an automated hermes-sweeper review.

[teknium1]

This allows a configured acknowledgement with no ⚡ Interrupting / ⏳ Queued / ⏩ Steered prefix. LINE detects busy acks solely by those prefixes (plugins/platforms/line/adapter.py:603-614) before bypassing its pending postback cache, so the localized/no-emoji templates requested by this feature can be swallowed. Please carry a structured busy-ack delivery marker instead of relying on rendered copy, and add a LINE pending-cache regression test.

[Bartok9]

Thanks @teknium1 / hermes-sweeper — good catch, addressed in 0d8c830.

Root cause: busy-ack templates route through gateway/run.py → _send_with_retry() → LINE send(), which only bypassed the pending-postback cache for the hardcoded _SYSTEM_BYPASS_PREFIXES. A localized / emoji-free template (the whole point of #26024) could therefore be cached instead of displayed.

Fix (structured marker, not string matching):

• gateway/run.py: the busy-ack send now carries a structured busy_ack=True marker in delivery metadata.
• plugins/platforms/line/adapter.py: LINE bypasses the postback cache when metadata['busy_ack'] is set, regardless of the operator-controlled template text. Prefix check retained as a fallback for callers that don't pass metadata.
• Added tests/plugins/test_line_busy_ack_bypass_26024.py — integration test exercising the gateway→LINE path with a prefix-free/localized template (asserts visible push, PENDING entry untouched), plus a control asserting normal responses still cache.

py_compile clean; new test + the 32 existing test_busy_ack_templates.py tests pass.

[Bartok9]

Fixed red CI (slice 2/8). The failure was tests/gateway/test_telegram_thread_fallback.py::test_gateway_runner_busy_ack_replies_to_triggering_message_for_telegram_dm_topic — a direct, expected consequence of this PR: busy acks now carry a structured busy_ack=True metadata marker (gateway/run.py) so platform adapters can bypass response-caching without string-matching operator-controlled template text. The test asserted exact metadata equality, so I updated it to expect the marker. Local: py_compile OK; test_telegram_thread_fallback.py 50/50 pass; test_busy_ack_templates.py + test_line_busy_ack_bypass_26024.py 34/34 pass. Force-with-lease pushed.

[Bartok9]

Rebased onto current origin/main to clear a CONFLICTING/DIRTY state (the prior head had drifted from main). Clean-rebuilt the three real commits on a fresh main tip:

• feat(gateway): configurable busy-ack messages (feat(gateway): make busy acknowledgement messages configurable #26024)
• fix(line): honor structured busy_ack marker so templates surface
• test(gateway): expect the busy_ack marker in the Telegram DM-topic metadata

Conflict resolution: main gained a new is_redirect_mode branch in GatewayRunner. Integrated it into the template dispatch — steer routes through the templates, and redirect preserves main's exact message via the same template-bypass pattern used for the #30170 subagent and compression special cases (assigns a valid _busy_mode_key + _busy_demoted_message). Behaviour on main is unchanged; the busy-ack templates remain fully backward-compatible with defaults.

Local: py_compile OK; 84/84 pass across test_telegram_thread_fallback.py, test_busy_ack_templates.py, and test_line_busy_ack_bypass_26024.py.

[Bartok9]

Re-based cleanly onto current origin/main to clear a conflict that arose from the recent hermes_cli/config.py → hermes_cli/config_defaults.py DEFAULT_CONFIG refactor (the busy_ack_templates default now lives in config_defaults.py). Also integrated main's new is_redirect_mode busy-ack branch, giving it a valid _busy_mode_key + explicit message (same pattern as the #30170 / compression special cases) so it can't fall through the template render.

py_compile OK; 54/54 tests pass (test_busy_ack_templates + test_line_busy_ack_bypass_26024 + test_telegram_thread_fallback). Feature is still absent on main and #26024 remains open. Ready for review.