Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix feat(gateway): expose queue depth/status API for busy_input_mode queue [3 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#28555•Fetched 2026-05-20 04:03:22
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
zccymanzccyman
Participants
wesleysimpliciowesleysimpliciozccymanzccyman
Timeline (top)
labeled ×3cross-referenced ×2commented ×1

Error Message

  • Return -1 or None if session is not found (not an error)

Fix Action

Fixed

PR fix notes

PR #28567: feat(gateway): expose queue depth API (#28555)

Description (problem / solution / changelog)

What does this PR do?

This PR exposes the existing gateway queue-depth calculation through a small public accessor on GatewayRunner.

Hermes already tracks queued follow-up work for busy sessions, but that state is only available through internal structures:

  • the adapter-level pending slot (_pending_messages)
  • the runner-level overflow buffer (_queued_events)
  • the private helper _queue_depth(...)

That makes queue observability awkward for any caller outside gateway internals. CLI surfaces, web/dashboard views, and integrations can all know a session key, but they do not have a supported way to ask, "how much queued work is waiting for this session right now?"

The goal here is to expose queue state without changing queue behavior.

Solution Sketch

  • introduce the smallest surface needed for the new capability in the touched subsystem
  • preserve existing behavior and defaults outside the new entry point or configuration path
  • cover the new path with focused validation before asking for review

Related Issue

Fixes #28555

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

  • added GatewayRunner.get_queue_depth(session_key) as a public entry point (gateway/run.py)
  • resolved the platform from canonical Hermes session keys such as agent:main:telegram:dm:... (gateway/run.py)
  • reused the existing _queue_depth(...) helper so slot + overflow semantics stay the same (gateway/run.py)
  • added regression coverage for queue depth resolution + overflow safety (tests/gateway/test_queue_consumption.py)

How to Test

  1. Run python -m pytest tests/gateway/test_queue_consumption.py -q -n 4.
  2. (Optional) Start a gateway session, enqueue multiple follow-ups for a busy session, and confirm GatewayRunner.get_queue_depth(session_key) increases as expected.

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: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->

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

  • N/A (no UI changes). If needed, I can attach a short log snippet showing queue depth increasing for a busy session.

Changed files

  • .github/CODEOWNERS (added, +1/-0)
  • gateway/run.py (modified, +21/-0)
  • tests/gateway/test_queue_consumption.py (modified, +36/-1)

PR #28586: feat(gateway): expose get_queue_depth and get_queue_status public API

Description (problem / solution / changelog)

Summary

Exposes the existing internal _queue_depth() method via two new public methods on GatewayRunner, making the busy_input_mode: queue internal state observable.

Motivation

After the FIFO queue fix in PR #28551, the queue state is still entirely opaque. Users and integrations have no way to query queue depth, making it impossible to verify FIFO behavior or display queue status in the CLI/web UI.

Changes

FileChange
gateway/run.py+2 public methods: get_queue_depth(), get_queue_status()
tests/gateway/test_queue_depth_api.py+8 unit tests covering all code paths

API

def get_queue_depth(self, session_key: str) -> int | None:
    """Return queued message count (slot + overflow). None = session not found."""

def get_queue_status(self, session_key: str) -> dict | None:
    """Return structured status: {session_key, depth, has_slot_message, overflow_count}."""

Test Results

tests/gateway/test_queue_depth_api.py — 8 passed
tests/gateway/test_busy_session_ack.py — 18 passed
tests/gateway/test_queue_consumption.py — 8 passed

Closes #28555

Changed files

  • gateway/run.py (modified, +40/-0)
  • tests/gateway/test_queue_depth_api.py (added, +108/-0)

Code Example

def get_queue_depth(self, session_key: str) -> int:
    """Return the number of queued messages for a session (slot + overflow)."""
    adapter = self.adapters.get(session_key.split(':')[0])
    return self._queue_depth(session_key, adapter=adapter)
RAW_BUFFERClick to expand / collapse

Problem

When busy_input_mode: queue is configured, users have no way to know whether their follow-up message was queued, how many messages are ahead of them, or when their message will be processed. The queue state is entirely opaque.

Proposed solution

Expose the existing internal queue state via a lightweight public API so clients (CLI, web UI, integrations) can query it.

Core API

gateway/run.py already has a _queue_depth() method and a _queued_events dict. We need to expose this through a public method on GatewayRunner:

def get_queue_depth(self, session_key: str) -> int:
    """Return the number of queued messages for a session (slot + overflow)."""
    adapter = self.adapters.get(session_key.split(':')[0])
    return self._queue_depth(session_key, adapter=adapter)

What clients can do with this

  • CLI: /queue status — shows "You have 3 messages in queue"
  • Web UI: badge/counter showing queue depth per session
  • Integration: webhook notification when queue depth crosses a threshold
  • Debugging: verify that rapid follow-ups are actually being queued in FIFO order (vs. the bug fixed in #28503)

Implementation notes

  • Use existing _queue_depth() — no new data structures needed
  • Should be safe to call from any thread context since it only reads
  • Session key format: {platform}:{user_id}:{chat_id}
  • Return -1 or None if session is not found (not an error)

Priority

P2 — improves observability of a feature that was previously undebuggable.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#dependency conflict#environment setup#docker error#permission error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix feat(gateway): expose queue depth/status API for busy_input_mode queue [3 pull requests, 1 comments, 2 participants]