fix: keep one-shot MCP resources alive through tool calls

[brandonriverott]

Summary

• wait for bounded MCP discovery before one-shot agent construction
• keep discovered MCP resources open through the conversation
• gracefully shut MCP servers down afterward
• add a regression test for discovery, first tool call, and cleanup ordering

Verification

• scripts/run_tests.sh tests/hermes_cli/test_mcp_startup.py tests/tools/test_mcp_tool.py tests/tools/test_mcp_probe.py -q
• 226 passed, 0 failed
• git diff --check passed

Safety

No provider, authentication, gateway, user configuration, or GBrain data changes.

[tonydwb]

Code Review Summary

Verdict: LGTM / Comment

Fix ensures MCP resources discovered in one-shot mode stay alive through tool call execution, then shut down cleanly afterward. The wait_for_mcp_discovery() call at the top and shutdown_mcp_servers() in a finally block are correct. Includes a dedicated test. No issues found.

[teknium1]

Thanks for addressing the one-shot MCP startup race. The premise is present on current main: hermes_cli/main.py:12866-12879 starts bounded background discovery for chat/one-shot launches, while hermes_cli/oneshot.py:393 constructs AIAgent without the CLI wrapper's discovery wait. The proposed wait therefore closes a real tool-snapshot gap.

Problems

• The new try/finally starts only after AIAgent(...) is constructed (hermes_cli/oneshot.py:426 in the PR diff). If construction raises after discovery has opened MCP servers, shutdown_mcp_servers() is never reached.

Suggested changes

• Start the protected region before AIAgent(...), so construction, callback setup, and the conversation all share the shutdown guarantee. Add a constructor-failure ordering test alongside the current happy-path test in tests/hermes_cli/test_mcp_startup.py.

This is an automated hermes-sweeper review.

[teknium1]

This try begins after AIAgent(...) construction. Please begin the protected region before construction so an initialization failure after MCP discovery still calls shutdown_mcp_servers().

[GottZ]

This was generated by AI during triage.

Summary

Twenty-three PRs address or reference the MCP discovery/tool-snapshot complex through timeout changes, pre-build readiness barriers, late refresh, worker-specific waits, or adjacent lifecycle work. Merged #49208 provides the multi-turn refresh foundation and merged #75933 implements the non-interactive discovery barrier, while target #66047 adds a distinct one-shot MCP resource-lifetime change.

Related pull requests

• fix(mcp): run MCP discovery synchronously for quiet-mode sessions #36882 best fix — (+245/-0) — n/a: Adds a bounded 30-second discovery join for chat -q with delayed and blocked-server tests, but its separate query-mode policy overlaps fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 and remains shorter than the documented 34-second Kanban startup; consistent with its keep_open verdict, salvage only stronger worker-specific coverage onto current main.
• fix(mcp): wait longer for headless discovery #37104 [closed] partial — (+50/-3) — n/a: Raises the old generic wait to three seconds and adds an environment override, reducing short cold-start races but not eliminating the bounded snapshot race; closed as stale and superseded by the config-backed designs in fix(mcp): expose late-connecting MCP tools to the agent (TUI/CLI/gateway) #49208 and fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933.
• fix(mcp): raise headless discovery timeout and add HERMES_MCP_DISCOVERY_WAIT override #37301 best fix — (+177/-13) — n/a: Adds five-second waits and duplicated environment/config resolution at obsolete CLI/TUI call sites; despite its keep_open review and recorded best-fix status for [Bug]: -z/headless oneshots silently drop slow-connecting MCP servers (0.75 s discovery wait too short for container/stdio-backed servers) #37013, merged fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 implements cause-level readiness through current paths and the supported config resolver.
• fix(mcp): respect HERMES_MCP_DISCOVERY_TIMEOUT env var for slow-connecting servers #37393 [closed] partial — (+33/-5) — n/a: Adds only a behavioral environment-variable override to the shared timeout resolver without repairing snapshot ordering; closed as not planned because current main already uses config-backed mcp_discovery_timeout.
• fix(oneshot): discover MCP tools before toolset snapshot (#38448) #38456 fixes — (+113/-0) — n/a: Runs raw synchronous MCP discovery before the one-shot snapshot, correcting ordering but bypassing bounded startup, configuration gating, and shared OAuth suppression; despite its keep_open review, fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 supplies the requested bounded shared-helper implementation.
• Fix/mcp discovery non gateway paths #38620 fixes — (+163/-0) — n/a: Places the shared bounded wait before one-shot construction and tests completion and timeout ordering; despite its keep_open verdict, fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 supersedes this narrower approach by also starting discovery when necessary and selecting the dedicated single-query bound.
• fix(mcp): increase wait_for_mcp_discovery timeout from 0.75s to 3.0s #41630 [closed] partial — (+3/-3) — n/a: Raises fixed CLI and TUI waits from 0.75 to three seconds, which only narrows the race; closed as already implemented more broadly on main through configurable waiting and cache-safe late refresh.
• fix(mcp): increase MCP discovery timeout for kanban workers #43348 best fix — (+69/-1) — n/a: Applies a Kanban-specific 60-second minimum that covers issue [Bug]: Kanban worker starts before MCP tools finish initializing — tools missing from early API calls #43273's documented 34-second startup and is a recorded best fix for [Bug]: Kanban worker starts before MCP tools finish initializing — tools missing from early API calls #43273 and One-shot kanban workers miss large MCP servers' tools (snapshot races discovery) #54691; its keep_open review requires rebasing the floor after the current config resolver and adding a worker-build regression.
• fix(mcp): bump default discovery wait from 0.75s to 3.0s for npx cold start #43685 [closed] partial — (+50/-3) — n/a: Duplicates fix(mcp): increase wait_for_mcp_discovery timeout from 0.75s to 3.0s #41630's three-second CLI/TUI timeout bump; closed as implemented on main, with the automated verdict citing commit 357fa7a50dce16ef696d81d55d385907a5c6e55e and the broader late-refresh path.
• [codex] Preserve agent continuity across cache and compression paths #47639 partial — (+461/-33) — n/a: Bundles a fixed six-second MCP wait with unrelated transport, compression, configuration, and credential changes; its keep_open review supports splitting out only the config-coercion fix and dropping the superseded MCP hunk.
• fix(mcp): expose late-connecting MCP tools to the agent (TUI/CLI/gateway) #49160 [closed] fixes — (+734/-48) — n/a: Introduces config-backed bounded discovery and thread-safe, generation-aware late tool refresh across CLI, TUI, and gateway while explicitly leaving one-shot out of scope; closed after its six commits were cherry-picked with attribution into fix(mcp): expose late-connecting MCP tools to the agent (TUI/CLI/gateway) #49208.
• fix(mcp): expose late-connecting MCP tools to the agent (TUI/CLI/gateway) #49208 [merged] best fix — (+734/-48) — n/a: Merged reference implementation for config-backed discovery waits and cache-safe between-turn snapshot refresh across CLI, TUI, and gateway, remaining relevant as the architecture extended by fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 for one-turn paths.
• fix(cli): wait full MCP cold-start in single-query mode (closes #51316) #51322 best fix — (+46/-0) — n/a: Proposes a dedicated larger single-query timeout, but the visible diff does not wire the reviewed top-level -z construction path; despite its keep_open review and recorded best-fix status, merged fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 implements the complete design for both chat -q and one-shot.
• fix: redirect interactive stderr away from TUI #52441 related — (+284/-19) — n/a: Redirects interactive stderr and bundles OAuth callback changes rather than establishing pre-snapshot readiness; its keep_open review requires preserving user-facing OAuth output, correcting IPv6 URI formatting, and splitting the concerns.
• fix(mcp): let one-shot kanban workers await large MCP discovery before snapshot #54695 [closed] partial — (+21/-1) — n/a: Adds a 90-second Kanban wait at the concrete worker-build path but exposes it through HERMES_KANBAN_MCP_WAIT; closed as not planned because behavioral timeouts must use config.yaml, leaving its placement as evidence for reworking fix(mcp): increase MCP discovery timeout for kanban workers #43348.
• fix(cli): wait for MCP before first-turn agent builds #60017 partial — (+212/-31) — n/a: Adds a start-and-wait helper before CLI and one-shot builds but globally raises the shared timeout and waits for effectively MCP-free invocations; despite its keep_open review, fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 supersedes the core helper while effective-toolset gating remains a focused salvage.
• fix(oneshot): join MCP discovery before the one-shot tool snapshot (bounded, gated, warns) #61944 best fix — (+269/-16) — n/a: Adds a config-resolved, effective-toolset-gated one-shot wait with pending-server warnings and skip-path tests; despite its keep_open review and recorded best-fix status, fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 supersedes readiness itself while selection gating and warning behavior remain distinct salvage.
• fix: keep one-shot MCP resources alive through tool calls #66047 fixes — (+66/-2) — n/a: Adds the one-shot wait and explicit MCP shutdown after tool execution, preserving resources through the conversation; consistent with its high-salvage keep_open review, the cleanup region must begin before AIAgent construction and gain a constructor-failure ordering test.
• fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162 [closed] best fix — (+98/-0) — n/a: Adds a failure-tolerant bounded wait before one-shot construction but uses the shorter shared bound; closed as superseded by main commit 3572d4bca, whose self-starting helper and 15-second single-query policy implement the recorded best fix for One-shot mode (-z) builds the agent without waiting for background MCP discovery — slow stdio servers are silently dropped #68137.
• fix: wait for MCP discovery in one-shot mode before building agent (#68137) #68168 [closed] fixes — (+111/-0) — n/a: Adds the same pre-construction one-shot wait without fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162's failure guard; closed as duplicate of fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162 and transitively superseded by fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933.
• fix(cli): wait for MCP discovery in one-shot mode #69174 fixes — (+47/-0) — n/a: Adds the same bounded pre-snapshot wait as fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162, but its test uses the obsolete chat() and string-return contract; despite its keep_open review, main commit 3572d4bca implements the broader start-if-needed single-query barrier.
• fix: wait for MCP discovery in one-shot mode before building agent (#68137) #71277 [closed] fixes — (+118/-0) — n/a: Repeats fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162's failure-tolerant pre-build wait with updated source-module patching; closed in favor of fix(cli): wait for background MCP discovery before building the one-shot agent (#68137) #68162 and transitively superseded by fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933.
• fix(mcp): ensure MCP discovery completes before agent build in non-interactive sessions #75933 [merged] best fix — (+417/-10) — n/a: Merged reference implementation that adds ensure_mcp_discovery_before_agent_build(), a configurable 15-second single-query bound, and pre-AIAgent wiring for both chat -q and top-level -z, directly resolving the core discovery-ordering cause.

Duplicates

#41630 and #43685 are the same three-second CLI/TUI timeout bump; #68168, #69174, and #71277 duplicate #68162's one-shot pre-build wait, and that chain is superseded by merged #75933; #38456, #38620, #51322, #60017, and the readiness portion of #61944 overlap #75933, while #43348 and #54695 share the Kanban-specific long-wait approach.

Suggested consolidation

Keep #66047 open with a salvage path: retain only its distinct MCP resource-lifetime guarantee, move the try/finally boundary before AIAgent construction, and add the constructor-failure cleanup test requested by the high-salvage keep_open review. The generic discovery wait in #66047 should be rebased onto merged #75933 rather than duplicated; the pure one-shot wait variants can remain closed or be closed as duplicates of #75933, while #43348 requires author action on its config-backed worker-specific floor.

Complex graph

flowchart TD
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I38448(["issue #38448 (closed)"])
    I51316(["issue #51316 (closed)"])
    I68137(["issue #68137 (closed)"])
    subgraph Dup36882 ["PRs duplicating each other"]
        P36882["PR #36882 (open)"]
        P38456["PR #38456 (open)"]
        P38620["PR #38620 (open)"]
        P51322["PR #51322 (open)"]
        P60017["PR #60017 (open)"]
        P61944["PR #61944 (open)"]
        P66047["PR #66047 (open)"]
        P68162["PR #68162 (closed)"]
        P68168["PR #68168 (closed)"]
        P69174["PR #69174 (open)"]
        P71277["PR #71277 (closed)"]
        P75933["PR #75933 (merged)"]
    end
    P66047 -.->|partial| I38448
    P66047 -.->|partial| I51316
    P66047 -->|fixes| I68137
    class I38448 closed
    class I51316 closed
    class I68137 closed
    class P36882 open
    class P38456 open
    class P38620 open
    class P51322 open
    class P60017 open
    class P61944 open
    class P66047 open
    class P68162 closed
    class P68168 closed
    class P69174 open
    class P71277 closed
    class P75933 merged
    class P36882 best
    class P51322 best
    class P51322 best
    class P51322 best
    class P61944 best
    class P61944 best
    class P68162 best
    class P75933 best
    class P75933 best
    class P75933 best
    class P75933 best
    class P75933 best
    class P66047 target
    click I38448 "https://github.com/NousResearch/hermes-agent/issues/38448"
    click I51316 "https://github.com/NousResearch/hermes-agent/issues/51316"
    click I68137 "https://github.com/NousResearch/hermes-agent/issues/68137"
    click P36882 "https://github.com/NousResearch/hermes-agent/pull/36882"
    click P38456 "https://github.com/NousResearch/hermes-agent/pull/38456"
    click P38620 "https://github.com/NousResearch/hermes-agent/pull/38620"
    click P51322 "https://github.com/NousResearch/hermes-agent/pull/51322"
    click P60017 "https://github.com/NousResearch/hermes-agent/pull/60017"
    click P61944 "https://github.com/NousResearch/hermes-agent/pull/61944"
    click P66047 "https://github.com/NousResearch/hermes-agent/pull/66047"
    click P68162 "https://github.com/NousResearch/hermes-agent/pull/68162"
    click P68168 "https://github.com/NousResearch/hermes-agent/pull/68168"
    click P69174 "https://github.com/NousResearch/hermes-agent/pull/69174"
    click P71277 "https://github.com/NousResearch/hermes-agent/pull/71277"
    click P75933 "https://github.com/NousResearch/hermes-agent/pull/75933"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 23 pull requests and 8 issues in this complex. Each diff was read against this issue; Assessment working set: 270 kB of PR diffs, 78 kB of issue/PR text, 72 kB of discussion (55 comments), 123 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.