fix(mcp): detect TimeoutError as stale session in StreamableHTTP transport

[lsl9119]

Problem

MCP tools connected via StreamableHTTP transport (e.g. actual-mcp-server) consistently time out with an empty error message ("call failed: "), even though direct HTTP POSTs to the same endpoint work fine.

Root cause: When the server closes the GET SSE long-poll stream after idle timeout (~60s), the python-sdk transport reconnects with a new session ID. But tool calls queued on the old session hang until the 120s tool_timeout fires. TimeoutError has an empty str(), so _is_session_expired_error() returns False, and the transport reconnect path is never triggered.

Evidence from agent.log

18:00:19  MCP server actual-mcp: registered 66 tools
18:05:19  GET stream disconnected, reconnecting in 1000ms...
23:41:11  ERROR: actual_accounts_list call failed:        ← empty error
23:49:24  GET stream disconnected...
23:53:43  ERROR: actual_accounts_list call failed:        ← empty error

Fix

_is_session_expired_error() now returns True for TimeoutError, triggering the existing _handle_session_expired_and_retry() path (transport reconnect + single retry). This is the same mechanism already used for "Invalid or expired session" text markers.

Changes

• tools/mcp_tool.py: Add isinstance(exc, TimeoutError) check before the text-marker matching
• tests/tools/test_mcp_tool_session_expired.py: Added test_is_session_expired_detects_timeout_error(). All 17 tests pass.

What this fixes

Before:
  GET stream disconnect → tool call timeout → "call failed: " → dead

After:
  GET stream disconnect → tool call timeout → reconnect + retry → success

Testing

pytest tests/tools/test_mcp_tool_session_expired.py -v
# 17 passed in 3.01s

The fix is narrow: it only affects _is_session_expired_error() which is guarded by _handle_session_expired_and_retry() — a path that already tears down and rebuilds the transport. No new failure modes are introduced.

[teknium1]

Thanks for tracing the reconnect path. The stale-session recovery gap remains on current main: tools/mcp_tool.py:3341-3344 only recognizes allow-listed message markers, so a bare timeout does not reach the reconnect helper.

Problems

• The proposed unconditional TimeoutError classification is too broad. Current main deliberately raises builtin TimeoutError for any MCP call that reaches its configured deadline (tools/mcp_tool.py:3664-3673; covered by tests/tools/test_mcp_tool.py:888-917). The changed test also treats TimeoutError("timed out") as stale. That would reconnect and invoke retry_call() again through tools/mcp_tool.py:3394-3410 for ordinary slow calls, not only a dead StreamableHTTP session.

Suggested changes

• Narrow the timeout predicate to a distinguishable stale transport/SDK condition, and preserve non-retry behavior for the local configured tool deadline.
• Add handler-level regression coverage for both cases: a safely classified stale timeout reconnects once, while an ordinary configured timeout does not reconnect or retry.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

Five PRs address the MCP stale-session recovery path: #15125 provides the merged reconnect-and-retry implementation, #13795 and most of #19208 overlap its current-main successor, while #17662 and #66841 propose additional timeout and INVALID_PARAMS classifiers that remain insufficiently discriminating.

Related pull requests

• #13795 [closed] related — (+510/-47) — implemented on main: The diff separates session-identity and dead-transport errors, including “Session terminated,” and routes tool, resource, and prompt operations through one reconnect plus one retry. Although closed, it remains relevant as a broader reference implementation now covered on main and shipped in v2026.5.7.
• #15125 [merged] related — (+540/-4) — merged reference implementation: The stale-session portion adds narrow message-based detection and reconnects all five MCP operation paths once, directly addressing expired server-side StreamableHTTP sessions; the PR also contains unrelated OAuth serialization, callback hardening, and redirect-security fixes.
• #17662 related — (+26/-1) — needs revision: Despite the keep_open review on #17662, the diff classifies every builtin TimeoutError as stale-session evidence, including ordinary configured tool-deadline expirations, and would therefore reconnect and repeat potentially slow calls without distinguishing a dead transport. Preserve the reported timeout gap, but add a transport-specific discriminator and handler-level positive/negative retry coverage before merging.
• #19208 related — (+334/-28) — partially superseded; salvage narrowly: Despite the keep_open review on #19208, the session-replacement wait and “Session terminated” recovery are already present in newer shared reconnect plumbing on main. The breaker reset is still useful, but the diff incorrectly converts every retry JSON payload containing an error key—including ordinary tool errors—into stale-transport failure, so only a focused _reset_server_error change should be retained.
• #66841 related — (+101/-1) — needs revision: Despite the keep_open review on #66841, the revised diff still classifies the exact generic McpError(-32602, “Invalid request parameters”) as stale-session evidence, although the same structural code and message can represent an ordinary JSON-RPC validation failure. The deployed-server repro is relevant, but the classifier needs an additional transport/session discriminator and a negative handler-level no-reconnect test.

Duplicates

#13795 and the stale-session/rebuilt-session portion of #19208 substantially overlap the reconnect-and-retry behavior merged via #15125 and subsequently strengthened on current main; #17662 and #66841 are distinct proposed classifier extensions, not duplicates of each other.

Suggested consolidation

Do not merge #17662, #19208, or #66841 as currently written. Treat merged #15125 and current main as the consolidated recovery implementation; keep #13795 closed as implemented-on-main, reduce #19208 to the focused full breaker-state reset, and require #17662 and #66841 to prove transport-specific predicates plus handler-level non-retry regressions before either classifier extension is eligible to merge.

Cross-PR triage: Reviewed 5 pull requests and 0 issues in this complex. Each diff was read against this issue; Assessment working set: 80 kB of PR diffs, 14 kB of issue/PR text, 6 kB of discussion (7 comments), 0 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.