Skip to content

feat: optional FastMCP skill + fix: gateway session race guard#2113

Merged
teknium1 merged 3 commits into
mainfrom
hermes/hermes-40b195db
Mar 20, 2026
Merged

feat: optional FastMCP skill + fix: gateway session race guard#2113
teknium1 merged 3 commits into
mainfrom
hermes/hermes-40b195db

Conversation

@teknium1

@teknium1 teknium1 commented Mar 20, 2026

Copy link
Copy Markdown
Contributor

Combined salvage PR

1. Optional FastMCP skill (salvage of #2096 by @kshitijk4poor)

Moved to optional-skills/mcp/fastmcp/ per maintainer request. Adds a FastMCP skill for building, testing, and deploying MCP servers with templates, scaffold script, and CLI reference. Closes #343.

2. Gateway session race guard (salvage of #2086 by @Gutslabs)

Fixes a race condition where two messages arriving in rapid succession for the same session can both bypass the _running_agents guard and spawn duplicate agents — corrupting the transcript.

Original fix (cherry-picked with authorship preserved):

  • Sentinel placed into _running_agents immediately after command dispatch, before any await
  • Async agent setup extracted into _handle_message_with_agent() wrapped in try/finally
  • Second message during sentinel gets queued instead of spawning a duplicate

Follow-up hardening:

  • /stop during sentinel returns helpful message instead of being queued as text
  • Shutdown loop skips sentinel entries instead of catching AttributeError
  • _handle_stop_command guards against sentinel defensively
  • 7 total tests covering all edge cases

All 1218 gateway tests pass, zero regressions.

@teknium1 teknium1 mentioned this pull request Mar 20, 2026
5 tasks
kshitijk4poor and others added 3 commits March 19, 2026 18:23
Add FastMCP skill to optional-skills/mcp/fastmcp/ with:
- SKILL.md with workflow, design patterns, quality checklist
- Templates: API wrapper, database server, file processor
- Scaffold CLI script for template instantiation
- FastMCP CLI reference documentation

Moved to optional-skills (requires pip install fastmcp).

Based on work by kshitijk4poor in PR #2096.
Closes #343
Place a sentinel in _running_agents immediately after the "already
running" guard check passes — before any await.  Without this, the
numerous await points between the guard (line 1324) and agent
registration (track_agent at line 4790) create a window where a
second message for the same session can bypass the guard and start
a duplicate agent, corrupting the transcript.

The await gap includes: hook emissions, vision enrichment (external
API call), audio transcription (external API call), session hygiene
compression, and the run_in_executor call itself.  For messages with
media attachments the window can be several seconds wide.

The sentinel is wrapped in try/finally so it is always cleaned up —
even if the handler raises or takes an early-return path.  When the
real AIAgent is created, track_agent() overwrites the sentinel with
the actual instance (preserving interrupt support).

Also handles the edge case where a message arrives while the sentinel
is set but no real agent exists yet: the message is queued via the
adapter's pending-message mechanism instead of attempting to call
interrupt() on the sentinel object.
- /stop during sentinel returns helpful message instead of queuing
- Shutdown loop skips sentinel entries instead of catching AttributeError
- _handle_stop_command guards against sentinel (defensive)
- Added tests for both edge cases (7 total race guard tests)
@teknium1 teknium1 force-pushed the hermes/hermes-40b195db branch from 3e0d810 to fc061c2 Compare March 20, 2026 01:26
@teknium1 teknium1 changed the title feat: add optional FastMCP skill for building MCP servers feat: optional FastMCP skill + fix: gateway session race guard Mar 20, 2026
@teknium1 teknium1 merged commit d9eba2a into main Mar 20, 2026
1 check failed
angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 27, 2026
…esearch#2113)

feat: optional FastMCP skill + fix: gateway session race guard
02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026
…esearch#2113)

feat: optional FastMCP skill + fix: gateway session race guard
olympus-terminal pushed a commit to olympus-terminal/hermes-agent that referenced this pull request May 16, 2026
…esearch#2113)

feat: optional FastMCP skill + fix: gateway session race guard
gweeteve pushed a commit to gweeteve/hermes-agent that referenced this pull request Jun 2, 2026
…esearch#2113)

feat: optional FastMCP skill + fix: gateway session race guard
Egavasyug pushed a commit to Egavasyug/hermes-agent that referenced this pull request Jun 10, 2026
…esearch#2113)

feat: optional FastMCP skill + fix: gateway session race guard
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: FastMCP Skill — Build, Test, and Deploy MCP Servers

3 participants