@yahyahammad/venastine 0.3.8 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,733 +1,780 @@
1
- """
2
- mcp_client/client.py
3
-
4
- The async bridge and the MCP client. ROADMAP_v2 §17, D2a/D23.
5
-
6
- The MCP SDK is async end to end with no synchronous surface. Making tool
7
- dispatch async to accommodate it would touch every file in this project
8
- and invalidate a wholly synchronous test suite, for a concurrency benefit
9
- nothing here needs. So ONE dedicated background thread owns ONE event
10
- loop for all MCP traffic, and every call crosses into it via
11
- run_coroutine_threadsafe(...).result(timeout=...). `_run()`,
12
- `registry.dispatch()` and every tool handler stay plain sync functions.
13
-
14
- --------------------------------------------------------------------
15
- THE MANAGER TASK -- read this before touching connect/disconnect
16
- --------------------------------------------------------------------
17
- §17's spec has connect_all() do `stack.enter_async_context(...)` and
18
- disconnect_all() call `stack.aclose()`. That does not work, and the
19
- failure is not theoretical -- it was reproduced against mcp 2.0.0 before
20
- this file was written:
21
-
22
- RuntimeError: Attempted to exit cancel scope in a different task
23
- than it was entered in
24
-
25
- Rev. 3 reasoned that the exit stack must live on the MCP *loop*, because
26
- entering on one loop and exiting on another is undefined. True, but not
27
- sufficient. anyio binds cancel scopes to the TASK, and
28
- run_coroutine_threadsafe() creates a NEW TASK for every call. Connecting
29
- in one task and closing from another is illegal even on the same loop.
30
-
31
- So a single long-lived _manager() task enters every context, signals
32
- ready, then parks on an event until shutdown -- the stack unwinds in the
33
- same task that entered it. Per-call tasks are fine: calling a method on a
34
- connected client doesn't exit anyone's cancel scope.
35
-
36
- If you ever see that RuntimeError again, something moved an
37
- enter/exit across the task boundary. The fix is never "use a different
38
- loop"; it is "do it inside _manager".
39
- """
40
-
41
- import asyncio
42
- import contextlib
43
- import json
44
- import logging
45
- import threading
46
- import time
47
- from typing import Optional
48
-
49
- from mcp import Client
50
- from mcp.client.sse import sse_client
51
- from mcp.client.stdio import StdioServerParameters, stdio_client
52
- from mcp.client.streamable_http import (
53
- create_mcp_http_client,
54
- streamable_http_client,
55
- )
56
- from mcp.shared.exceptions import MCPError
57
-
58
- import config as _harness_config
59
- from safety.policy_enforcement import TOKEN_CHARS, fragment_end
60
-
61
- logger = logging.getLogger(__name__)
62
-
63
- # Rev. 1 S12: MCP servers are third-party code and can hang. A generous default
64
- # beats an indefinite block; individual calls may override.
65
- DEFAULT_CALL_TIMEOUT_S = 180.0
66
- CONNECT_TIMEOUT_S = 60.0
67
- SHUTDOWN_TIMEOUT_S = 15.0
68
-
69
- # F6 (#64): the WHOLE teardown -- polite close, force-cancel, loop-thread
70
- # join -- shares this one wall-clock budget, instead of three sequential
71
- # SHUTDOWN_TIMEOUT_S waits whose worst case hung a quitting harness ~45s.
72
- # Master value lives in config.py beside the other harness bounds; the
73
- # re-export here keeps it beside its sibling timeouts and gives tests a
74
- # single name to shrink.
75
- TEARDOWN_BUDGET_S = _harness_config.TEARDOWN_BUDGET_S
76
-
77
- # How much of a structured error payload rides in the error STRING.
78
- # D23 promises call_tool() returns one error shape, so a server's
79
- # structured_content on a failure belongs inside that string rather than
80
- # in a second key every consumer of a dispatch error would have to learn
81
- # (A32). Bounded because the payload is third-party and the string reaches
82
- # a model: 500 is room for the {code, retry_after, message} an error
83
- # payload actually carries, and the cut is visible for the reason
84
- # _catalog_text's is.
85
- #
86
- # The result AS A WHOLE has its own bound, `max_read_chars` (A79); see
87
- # _normalize.
88
- MAX_ERROR_DETAIL_CHARS = 500
89
-
90
- # Per-server, inside the manager. CONNECT_TIMEOUT_S is the caller-side
91
- # budget for ALL servers together; without a per-server bound one hung
92
- # handshake spends it and every server after it in the loop is starved of
93
- # time it never got to use.
94
- SERVER_CONNECT_TIMEOUT_S = 20.0
95
-
96
- # How far below the caller-side timeout the protocol-level timeout sits.
97
- # Both are set, and they do different jobs: read_timeout_seconds cancels
98
- # the REQUEST at the protocol level, while future.result(timeout=) only
99
- # unblocks the calling thread and abandons the call locally. The margin
100
- # makes the protocol one win the race, so a hung server is told to stop
101
- # rather than merely stopped being waited on, and the caller gets the
102
- # SDK's specific MCPError instead of a bare TimeoutError.
103
- #
104
- # The future timeout is still needed as a backstop for the case the
105
- # protocol one can't cover: a wedged loop, where no MCP-level response
106
- # (including the timeout) is coming at all.
107
- _TIMEOUT_MARGIN_S = 5.0
108
-
109
- class _TrackClose:
110
- """Records that one server's session closed cleanly, so a teardown
111
- that runs out of budget can NAME which server ignored the shutdown
112
- request instead of reporting an anonymous hang (F6).
113
-
114
- Recorded only on an unexceptional exit: a session whose __aexit__
115
- raised, or was interrupted by the force-cancel, did not demonstrably
116
- close -- and "we stopped waiting for it" is exactly what the
117
- straggler line means. Attribute access forwards to the real client,
118
- so list_tools()/call_tool() never notice the wrapper.
119
- """
120
-
121
- def __init__(self, inner, name: str, closed: set):
122
- self._inner = inner
123
- self._name = name
124
- self._closed = closed
125
-
126
- async def __aenter__(self):
127
- return await self._inner.__aenter__()
128
-
129
- async def __aexit__(self, *exc):
130
- try:
131
- result = await self._inner.__aexit__(*exc)
132
- except BaseException:
133
- raise
134
- self._closed.add(self._name)
135
- return result
136
-
137
- def __getattr__(self, item):
138
- return getattr(self._inner, item)
139
-
140
-
141
- _loop: Optional[asyncio.AbstractEventLoop] = None
142
- _thread: Optional[threading.Thread] = None
143
- _loop_lock = threading.Lock()
144
-
145
-
146
- def _ensure_loop() -> asyncio.AbstractEventLoop:
147
- """The one MCP event loop, created on first use."""
148
- global _loop, _thread
149
- with _loop_lock:
150
- if _loop is None:
151
- _loop = asyncio.new_event_loop()
152
- _thread = threading.Thread(
153
- target=_loop.run_forever, name="mcp-loop", daemon=True)
154
- _thread.start()
155
- logger.debug("Started MCP event loop thread.")
156
- return _loop
157
-
158
-
159
- def _shutdown_loop(join_timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
160
- global _loop, _thread
161
- with _loop_lock:
162
- if _loop is None:
163
- return
164
- _loop.call_soon_threadsafe(_loop.stop)
165
- if _thread is not None:
166
- _thread.join(timeout=join_timeout)
167
- if _thread.is_alive():
168
- logger.warning("MCP loop thread did not stop within %.1fs.",
169
- join_timeout)
170
- _loop = None
171
- _thread = None
172
-
173
-
174
- def _detail(structured) -> str:
175
- """A structured payload as one bounded line, for the error string.
176
-
177
- default=str so a payload holding something JSON cannot carry is still
178
- reported rather than raising inside the error path -- D23's promise
179
- that this module returns one error shape has to mean always, which is
180
- the same argument the broad except in call_tool() makes.
181
- """
182
- try:
183
- rendered = json.dumps(structured, default=str, sort_keys=True)
184
- except Exception:
185
- rendered = repr(structured)
186
- rendered = " ".join(rendered.split())
187
- if len(rendered) <= MAX_ERROR_DETAIL_CHARS:
188
- return rendered
189
- return rendered[:MAX_ERROR_DETAIL_CHARS - 1].rstrip() + "\u2026"
190
-
191
-
192
- def _cut(text: str, limit: int) -> str:
193
- """The first *limit* characters of *text*, less a word the cut split.
194
-
195
- The redactor runs after this, on the dispatch path, and cannot match
196
- half a credential. So when the character past the cut is a token
197
- character, the token-character run the cut ends inside goes too: the
198
- rule A72 made for a shell session's dropped middle. A cut that fell
199
- between two words drops nothing more.
200
- """
201
- if len(text) <= limit:
202
- return text
203
- kept = text[:limit]
204
- if text[limit] in TOKEN_CHARS:
205
- kept = kept[:fragment_end(kept)]
206
- return kept
207
-
208
-
209
- def _json_chars(structured) -> Optional[int]:
210
- """How many characters *structured* takes as JSON, or None when it
211
- cannot be rendered -- which _normalize reads as too large to keep,
212
- since nothing can say how large it is."""
213
- try:
214
- return len(json.dumps(structured, default=str, ensure_ascii=False))
215
- except Exception:
216
- return None
217
-
218
-
219
- def _repeats(structured, text: str) -> bool:
220
- """Whether *structured* is the server's text over again.
221
-
222
- The SDK's own server sends a tool that returns a string as that text
223
- AND as `{"result": <the text>}`, and a typed return as the JSON in
224
- both places. A dropped copy of the text is no loss, and the note says
225
- so, so the model does not call again for something it already has.
226
- """
227
- if structured == {"result": text}:
228
- return True
229
- try:
230
- return json.loads(text) == structured
231
- except Exception:
232
- return False
233
-
234
-
235
- def _normalize(result, tool_name: str = "") -> dict:
236
- """CallToolResult -> the plain dict shape every other tool handler
237
- returns (D23).
238
-
239
- Fixing this at the producer rather than the consumer is the whole
240
- point. Downstream, check_output_policy() calls result.get(key) and
241
- would raise AttributeError on a pydantic model -- meaning MCP output,
242
- the output most likely to come from code the user didn't write, is
243
- exactly the output that would bypass secret redaction. And
244
- memory.add_tool_result() would str() a pydantic repr into the thread.
245
-
246
- MCP signals tool failure IN BAND via is_error rather than by raising,
247
- so it maps onto the same {"error": ...} convention _run() already
248
- understands for ToolCallDenied and disallowed tools. No new error
249
- channel, no special-casing in the loop.
250
-
251
- Keys are 'content' and 'result' deliberately, though NOT for the
252
- reason this comment used to give. It said both were in
253
- safety/policy_enforcement.py's `_SCANNED_KEYS`, so MCP output was
254
- secret-redacted by the existing layer with no change to it. That set
255
- no longer exists (#47): check_output_policy scans every value, so any
256
- key would now be covered. Choosing these two is about matching the
257
- shape every other handler returns (D23), not about clearing a
258
- redaction bar.
259
-
260
- Worth keeping as a caution rather than deleting: this docstring is
261
- the evidence that authors DID read the allowlist as a contract and
262
- write to it. Two older built-ins returned `results` and never
263
- satisfied it, which is the defect #47 records.
264
-
265
- v2 renamed these fields to snake_case (.content/.structured_content/
266
- .is_error); §17's sketch reads the v1 camelCase spellings and would
267
- silently see is_error as always-False against v2.
268
-
269
- THE RESULT IS BOUNDED HERE, AS A WHOLE, AT `max_read_chars` (A79).
270
- Every other producer of third-party text bounds what it hands on, and
271
- this one handed on anything: 10 MB of text, of structured content or
272
- of an error message went through whole, into the thread and the
273
- model's context, behind a redaction pass that took 1.2-2.5 s over it.
274
- The server's text is cut at the bound with a note giving the size it
275
- had. A structured payload is kept whole if it fits in what the text
276
- left of the bound, and otherwise dropped with a note -- never cut,
277
- since a JSON document cut short can read as complete. A server that
278
- follows the MCP spec sends structured output as text as well, so the
279
- text usually carries what was dropped, and the note says when it was
280
- a repeat (see `_repeats`). The bound is `max_read_chars`
281
- because it is already how much one read is, and the compaction
282
- headroom check measures a read against it.
283
- """
284
- bound = int(_harness_config.MAX_READ_CHARS)
285
- blocks = getattr(result, "content", None) or []
286
- kept, dropped = [], []
287
- for block in blocks:
288
- kind = getattr(block, "type", None) or "unknown"
289
- if kind == "text":
290
- value = getattr(block, "text", None)
291
- if value:
292
- kept.append(value)
293
- # AN EMPTY TEXT BLOCK HAS NOTHING TO DROP. It is filtered out
294
- # of the join either way, but counting it as dropped content
295
- # made the placeholder contradict itself -- `text("")` came
296
- # back as "[non-text MCP content: text]", reporting the kind
297
- # as non-text when the kind is text.
298
- continue
299
- dropped.append(kind)
300
-
301
- full = "\n".join(kept)
302
- text = _cut(full, bound)
303
- sent, shown = len(full), len(text)
304
- if dropped:
305
- # APPENDED, NOT SUBSTITUTED (A32). Non-text blocks (images,
306
- # embedded resources) are still dropped -- the harness has no
307
- # multimodal tool-result path, and inventing one here is scope the
308
- # rest of the design can't carry. What changed is WHEN the
309
- # disclosure happens: the placeholder used to fire only when NO
310
- # text survived, so a result carrying text AND non-text dropped
311
- # the non-text silently, and "Chart generated:" with no chart and
312
- # no note is a result the model will answer from. CallToolResult.
313
- # content is a REQUIRED list of mixed block types on the installed
314
- # SDK, so that shape is first-class in the protocol rather than
315
- # hypothetical.
316
- kinds = ", ".join(sorted(set(dropped)))
317
- note = f"[non-text MCP content: {kinds}]"
318
- text = f"{text}\n{note}" if text else note
319
- # ONE WARNING NAMING THE TOOL AND WHAT CHANGED, which is the rule
320
- # #49 was filed to establish and which this function broke on all
321
- # three of its dropping paths. The tool name is a PARAMETER
322
- # because this function could not name the tool -- it took the
323
- # result alone, so the rule was unsatisfiable here as written.
324
- logger.warning(
325
- "MCP tool %s returned %d non-text block(s) (%s); this harness "
326
- "has no multimodal tool-result path, so they were dropped and "
327
- "the result says so in band.",
328
- tool_name or "<unknown>", len(dropped), kinds)
329
-
330
- if shown < sent:
331
- # After the non-text note, so neither note is what the cut takes.
332
- note = (f"[MCP result cut: the server sent {sent:,} characters of "
333
- f"text, and the {shown:,} shown end at the last word break "
334
- f"inside the bound, max_read_chars ({bound:,})]")
335
- text = f"{text}\n{note}" if text else note
336
- logger.warning(
337
- "MCP tool %s returned %d characters of text; it was cut to %d "
338
- "(max_read_chars is %d) and the result says so in band.",
339
- tool_name or "<unknown>", sent, shown, bound)
340
-
341
- structured = getattr(result, "structured_content", None)
342
- if getattr(result, "is_error", False):
343
- message = text or "MCP tool call failed"
344
- if structured is not None:
345
- # D23's ONE error shape, not a second key (A32): a server
346
- # reporting {code: 429, retry_after: 30} used to lose it
347
- # entirely, so the one thing that would have explained the
348
- # failure was the one thing dropped.
349
- detail = _detail(structured)
350
- message = f"{message} (server detail: {detail})"
351
- logger.warning(
352
- "MCP tool %s failed with a structured payload; it is "
353
- "folded into the error string: %s",
354
- tool_name or "<unknown>", detail)
355
- return {"error": message}
356
-
357
- if structured is not None:
358
- size, room = _json_chars(structured), bound - shown
359
- if size is None or size > room:
360
- if size is None:
361
- why = "it could not be rendered as JSON to be measured"
362
- else:
363
- why = (f"it is {size:,} characters as JSON, and the text "
364
- f"left {room:,} of the bound, max_read_chars "
365
- f"({bound:,})")
366
- if _repeats(structured, full):
367
- why += "; it repeats the server's text"
368
- note = f"[MCP structured result dropped: {why}]"
369
- text = f"{text}\n{note}" if text else note
370
- logger.warning(
371
- "MCP tool %s returned structured content of %s characters "
372
- "with %d left of max_read_chars; it was dropped and the "
373
- "result says so in band.",
374
- tool_name or "<unknown>",
375
- "unmeasurable" if size is None else size, room)
376
- structured = None
377
-
378
- out = {"content": text}
379
- if structured is not None:
380
- out["result"] = structured
381
- return out
382
-
383
-
384
- class MCPClient:
385
- """Connects to configured MCP servers and exposes a synchronous
386
- call_tool() that looks completely ordinary to registry.dispatch()."""
387
-
388
- def __init__(self, server_configs: dict):
389
- # Set, and inspectable (§17 AC1). Rev. 1 omitted this assignment
390
- # entirely -- a real bug (C10) that made every later method fail
391
- # on a missing attribute.
392
- self.server_configs = server_configs
393
- self.clients: dict = {}
394
- self.failures: dict = {} # server name -> why it isn't usable
395
- self._closed: set = set() # servers whose session closed cleanly
396
- # F8 (#63): the catalogue gathered during connect, inside that
397
- # call's per-server timeout. Registration serves from here --
398
- # which removes MCP's one bridge call with NO protocol timeout,
399
- # and the window where a slow post-connect listing burned its
400
- # own 30s. A miss falls back to fetching.
401
- self._catalogs: dict = {}
402
- self._ready: Optional[asyncio.Event] = None
403
- self._shutdown: Optional[asyncio.Event] = None
404
- self._done: Optional[asyncio.Event] = None
405
- self._task = None
406
-
407
- # -- connection ------------------------------------------------------
408
-
409
- def _transport_for(self, cfg):
410
- """SDK object for one server. v2 collapsed v1's stdio-vs-HTTP
411
- branch: Client() takes a Transport, a URL string, or an in-process
412
- server object, so this returns whichever and Client sorts it out."""
413
- if cfg.transport == "stdio":
414
- return stdio_client(StdioServerParameters(
415
- command=cfg.command,
416
- args=[str(a) for a in cfg.args],
417
- env=cfg.env or None,
418
- cwd=cfg.cwd,
419
- ))
420
- if cfg.transport == "sse":
421
- # SSE must ALWAYS build its own transport: a bare URL string
422
- # means STREAMABLE HTTP to Client(), which is exactly the
423
- # silent misconnection #62 records. Headers go straight to
424
- # the SDK (its signature takes `headers=`), through the same
425
- # create_mcp_http_client defaults -- so an Authorization
426
- # header authenticates here too, never discarded (M19's
427
- # property holds on both HTTP transports).
428
- return sse_client(
429
- cfg.url,
430
- headers=dict(cfg.headers) or None,
431
- )
432
- if cfg.transport == "http":
433
- # `headers` was parsed into ServerConfig and then never used:
434
- # a bare URL carries none of them, so a server configured with
435
- # an Authorization header connected UNAUTHENTICATED, with
436
- # nothing indicating they had been discarded. In v2 headers
437
- # live on the httpx2 client, and the SDK ships the helper that
438
- # applies its own MCP defaults alongside them -- so this uses
439
- # that rather than hand-building a client and losing the
440
- # SSE-friendly timeouts. Without headers the SDK builds its own
441
- # client, exactly as Client() does for a bare URL.
442
- #
443
- # NEVER a bare URL now, even without headers (batch 208): mcp
444
- # 2.3.0 fails a call whose one server-sent event exceeds
445
- # `max_sse_event_size`, and a bare URL takes the SDK's 1 MiB,
446
- # which a streamed screenshot passes. config.yaml's
447
- # `mcp_max_event_bytes` is the ceiling, read per connection. It
448
- # bounds STREAMED answers only: one sent as plain JSON is read
449
- # whole (CONFIG_ARCHITECTURE.md has the measurement). The legacy
450
- # "sse" branch above keeps the SDK's fixed 1 MiB: `sse_client`
451
- # takes no size.
452
- return streamable_http_client(
453
- cfg.url,
454
- http_client=(create_mcp_http_client(headers=dict(cfg.headers))
455
- if cfg.headers else None),
456
- max_sse_event_size=_harness_config.MCP_MAX_EVENT_BYTES,
457
- )
458
- raise ValueError(cfg.error or "unusable server configuration")
459
-
460
- @staticmethod
461
- def _reason(e: BaseException, budget: Optional[float] = None) -> str:
462
- """Why a server is unusable, in one string for BOTH consumers.
463
-
464
- Batch 121, from the owner's log: `MCP server 'joplin' failed to
465
- connect: ` and nothing after the colon. The per-server
466
- asyncio.timeout raises TimeoutError, whose str() is "" -- so the
467
- %s below rendered nothing, and the one message that explains a
468
- silent MCP named no cause at all.
469
-
470
- It was also TWO strings: `failures` carried the exception type and
471
- the log line did not, so the better of the two never reached the
472
- place a user looks first. One copy now, and the timeout names its
473
- budget because "it timed out" without a duration leaves the
474
- reader unable to tell a dead server from a slow one.
475
- """
476
- text = str(e)
477
- if text:
478
- return f"{type(e).__name__}: {text}"
479
- if isinstance(e, TimeoutError) and budget is not None:
480
- return f"{type(e).__name__} (no handshake within {budget}s)"
481
- return type(e).__name__
482
-
483
- async def _manager(self):
484
- """Owns the AsyncExitStack for the whole process lifetime, in ONE
485
- task. See the module docstring -- this shape is required, not
486
- stylistic."""
487
- try:
488
- async with contextlib.AsyncExitStack() as stack:
489
- for name, cfg in self.server_configs.items():
490
- if cfg.disabled:
491
- logger.info("MCP server %r is disabled; skipping.", name)
492
- continue
493
- try:
494
- # PER-SERVER bound, not just the caller's blanket
495
- # one. v2's list_tools() takes no
496
- # read_timeout_seconds, so a server that spawns and
497
- # then never answers the handshake would otherwise
498
- # consume the whole shared connect budget and starve
499
- # every server after it in this loop.
500
- async with asyncio.timeout(SERVER_CONNECT_TIMEOUT_S):
501
- client = await stack.enter_async_context(
502
- _TrackClose(
503
- Client(self._transport_for(cfg)), name,
504
- self._closed)
505
- )
506
- # Validation is by connection (§17 decision G):
507
- # a server that connects AND lists its tools is
508
- # usable. The listing IS registration's
509
- # catalogue (F8): cached below, served from,
510
- # never fetched a second time.
511
- tools = await client.list_tools()
512
- self.clients[name] = client
513
- self._catalogs[name] = list(tools.tools)
514
- logger.info("MCP server %r connected (%d tools).",
515
- name, len(tools.tools))
516
- except Exception as e:
517
- # One unreachable server must never take down the
518
- # others, or a single stale entry makes the whole
519
- # harness unusable. §17's sketch had no try/except
520
- # here at all.
521
- why = self._reason(e, SERVER_CONNECT_TIMEOUT_S)
522
- self.failures[name] = why
523
- logger.warning("MCP server %r failed to connect: %s",
524
- name, why)
525
- self._ready.set()
526
- await self._shutdown.wait()
527
- except Exception:
528
- logger.exception("MCP manager task failed")
529
- if self._ready is not None and not self._ready.is_set():
530
- self._ready.set()
531
- finally:
532
- if self._done is not None:
533
- self._done.set()
534
-
535
- def connect_all(self, timeout: float = CONNECT_TIMEOUT_S) -> None:
536
- """Connect every configured server. Synchronous, callable from
537
- ordinary startup code; the bridge does the rest."""
538
- if not self.server_configs:
539
- return
540
- if self._task is not None:
541
- # #219, batch 213, the owner's choice of raising over tearing
542
- # down first. Every attribute below is rebound, so a second call
543
- # used to abandon the first generation's manager parked on a
544
- # `_shutdown` nothing could set any more -- its child processes
545
- # with it, and no straggler warning. Nothing reconnects today
546
- # (one call site, main.py); F7's runtime /mcp would, and it has
547
- # to disconnect on purpose.
548
- raise RuntimeError(
549
- "connect_all() on an MCP client that is already connected; "
550
- "call disconnect_all() first")
551
- loop = _ensure_loop()
552
-
553
- async def _start():
554
- self._ready = asyncio.Event()
555
- self._shutdown = asyncio.Event()
556
- self._done = asyncio.Event()
557
- self._task = loop.create_task(self._manager())
558
- await self._ready.wait()
559
-
560
- started = asyncio.run_coroutine_threadsafe(_start(), loop)
561
- try:
562
- started.result(timeout=timeout)
563
- except Exception:
564
- # A timeout here used to abandon the manager permanently. It
565
- # would still be parked mid-connect holding every child process
566
- # already spawned, and NOTHING could close it: disconnect_all()
567
- # waits on _done, which a stuck manager never sets. So one hung
568
- # server orphaned every other server's subprocess -- the exact
569
- # inversion of this file's "one unreachable server must never
570
- # take down the others" invariant.
571
- #
572
- # `started` IS RELEASED TOO (A33), and it is a different object
573
- # from the manager: _start() is still awaiting _ready when the
574
- # caller's budget runs out, and the two lines below stop the
575
- # loop out from under it. Left pending, asyncio reports "Task
576
- # was destroyed but it is pending!" through its own logger at
577
- # whatever moment the GC gets to it -- and the TUI's
578
- # TranscriptLogHandler is on the ROOT logger, so that line can
579
- # surface in a user's transcript naming nothing and
580
- # attributable to nothing. Cancelled FIRST, while the loop is
581
- # still running to deliver it; _cancel_manager() needs the
582
- # same loop alive and _shutdown_loop() is what ends it.
583
- started.cancel()
584
- self._cancel_manager()
585
- self.clients.clear()
586
- self._catalogs.clear()
587
- self._task = None
588
- _shutdown_loop()
589
- raise
590
-
591
- # -- calling ---------------------------------------------------------
592
-
593
- def list_tools(self, server_name: str, timeout: float = 30.0):
594
- """The server's tool catalogue. Serves the connect-time cache
595
- (F8) -- the one MCP call that had no protocol timeout -- and
596
- crosses the bridge only on a miss. A copy comes back, so a
597
- caller cannot mutate the cache."""
598
- cached = self._catalogs.get(server_name)
599
- if cached is not None:
600
- return list(cached)
601
- client = self.clients[server_name]
602
- fut = asyncio.run_coroutine_threadsafe(client.list_tools(), _ensure_loop())
603
- return fut.result(timeout=timeout).tools
604
-
605
- def call_tool(self, server_name: str, tool_name: str, params: dict,
606
- timeout: float = DEFAULT_CALL_TIMEOUT_S) -> dict:
607
- """The synchronous entry point every ToolSpec.handler calls.
608
-
609
- Looks ordinary to registry.dispatch() regardless of whether the
610
- caller sits on Textual's main loop, a worker thread, or a plain
611
- CLI script -- the bridge is what makes caller context irrelevant.
612
-
613
- Returns a plain dict, never a CallToolResult (D23, §17 AC6).
614
- """
615
- client = self.clients.get(server_name)
616
- if client is None:
617
- reason = self.failures.get(server_name, "not connected")
618
- return {"error": f"MCP server {server_name!r} is unavailable: {reason}"}
619
-
620
- loop = _ensure_loop()
621
- protocol_timeout = max(1.0, timeout - _TIMEOUT_MARGIN_S)
622
- coro = client.call_tool(tool_name, params,
623
- read_timeout_seconds=protocol_timeout)
624
- future = asyncio.run_coroutine_threadsafe(coro, loop)
625
- try:
626
- return _normalize(future.result(timeout=timeout), tool_name)
627
- except MCPError as e:
628
- # v2 raises for protocol-level failures -- including timeout,
629
- # which is code -32001 -- where v1 reported everything in
630
- # band. Map onto the same {"error": ...} convention so the
631
- # loop keeps exactly one error shape to understand.
632
- return {"error": f"MCP call failed: {e}"}
633
- except TimeoutError:
634
- # The protocol timeout should have fired first. Reaching here
635
- # means the loop itself is wedged; cancel so the coroutine
636
- # can't outlive the call.
637
- future.cancel()
638
- return {"error": f"MCP tool {tool_name!r} timed out after {timeout}s"}
639
- except Exception as e:
640
- # LAST, so the two specific branches above keep their handling
641
- # (notably future.cancel()). MCPError is not the only thing v2
642
- # raises: an outputSchema violation surfaces as a bare
643
- # RuntimeError and a malformed payload as a pydantic
644
- # ValidationError. dispatch() has no handler-exception catch
645
- # and _run() catches only ToolCallDenied, so anything escaping
646
- # here takes down the whole conversation -- or all ten research
647
- # passes -- on one buggy third-party server. D23 promises this
648
- # function returns ONE error shape; that has to mean always.
649
- logger.debug("MCP call raised", exc_info=True)
650
- return {"error": f"MCP call failed: {type(e).__name__}: {e}"}
651
-
652
- # -- shutdown --------------------------------------------------------
653
-
654
- def _cancel_manager(self, timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
655
- """Force the manager task to unwind its exit stack.
656
-
657
- Cancellation is the ONLY way to close the stack from outside the
658
- graceful path, and it works for the same reason the graceful path
659
- does: CancelledError is raised inside the manager's `async with`,
660
- so __aexit__ runs in the task that entered it. Calling aclose()
661
- from any other task is the cancel-scope error this module's
662
- docstring is about.
663
- """
664
- task, loop = self._task, _loop
665
- if task is None or loop is None:
666
- return
667
- try:
668
- async def _cancel():
669
- task.cancel()
670
- if self._done is not None:
671
- await self._done.wait()
672
- asyncio.run_coroutine_threadsafe(_cancel(), loop).result(timeout=timeout)
673
- except Exception as e:
674
- logger.warning("MCP manager task did not cancel cleanly: %s", e)
675
-
676
- def disconnect_all(self, timeout: float = None) -> None:
677
- """Close every session and stop the loop thread.
678
-
679
- Not tidiness: stdio servers are child processes THIS harness
680
- spawned. The daemon thread dies at interpreter exit without
681
- unwinding the stack, and the failure mode is orphaned
682
- subprocesses accumulating across sessions.
683
-
684
- F6 (#64): `timeout` is ONE budget for everything -- the polite
685
- close gets its first slice, force-cancel takes what remains
686
- (minus a join reserve), the loop-thread join takes the rest. It
687
- used to be three sequential SHUTDOWN_TIMEOUT_S waits, so one
688
- wedged server hung a quitting harness ~45s and Ctrl+C paid all
689
- of it. Servers that never confirmed a clean close by expiry are
690
- named in a WARNING.
691
- """
692
- budget = TEARDOWN_BUDGET_S if timeout is None else timeout
693
- if self._task is None or _loop is None:
694
- _shutdown_loop()
695
- return
696
-
697
- started = time.monotonic()
698
-
699
- def remaining() -> float:
700
- return max(0.0, budget - (time.monotonic() - started))
701
-
702
- graceful = False
703
- try:
704
- async def _stop():
705
- self._shutdown.set()
706
- await self._done.wait()
707
- asyncio.run_coroutine_threadsafe(_stop(), _loop).result(
708
- timeout=max(1.0, budget * 0.6))
709
- graceful = True
710
- except Exception as e:
711
- logger.warning("MCP shutdown did not complete cleanly within "
712
- "%.1fs of the %.1fs teardown budget: %s",
713
- max(1.0, budget * 0.6), budget, e)
714
- if not graceful:
715
- # The stack is still open and the children are still ours.
716
- # Asking politely didn't work, so cancel -- otherwise this
717
- # returns having reaped nothing while reporting only a warning.
718
- self._cancel_manager(timeout=max(1.0, remaining() - 1.0))
719
-
720
- stragglers = sorted(set(self.clients) - self._closed)
721
- if stragglers:
722
- logger.warning(
723
- "MCP server(s) %s did not confirm a clean close within the "
724
- "%.1fs teardown budget; their child processes may outlive "
725
- "this session.", ", ".join(stragglers), budget)
726
-
727
- self.clients.clear()
728
- self._catalogs.clear()
729
- # #219. Keyed by server name, so a clean close kept from this
730
- # generation would answer for the next one's straggler check.
731
- self._closed.clear()
732
- self._task = None
733
- _shutdown_loop(join_timeout=max(0.5, remaining()))
1
+ """
2
+ mcp_client/client.py
3
+
4
+ The async bridge and the MCP client. ROADMAP_v2 §17, D2a/D23.
5
+
6
+ The MCP SDK is async end to end with no synchronous surface. Making tool
7
+ dispatch async to accommodate it would touch every file in this project
8
+ and invalidate a wholly synchronous test suite, for a concurrency benefit
9
+ nothing here needs. So ONE dedicated background thread owns ONE event
10
+ loop for all MCP traffic, and every call crosses into it via
11
+ run_coroutine_threadsafe(...).result(timeout=...). `_run()`,
12
+ `registry.dispatch()` and every tool handler stay plain sync functions.
13
+
14
+ --------------------------------------------------------------------
15
+ THE MANAGER TASK -- read this before touching connect/disconnect
16
+ --------------------------------------------------------------------
17
+ §17's spec has connect_all() do `stack.enter_async_context(...)` and
18
+ disconnect_all() call `stack.aclose()`. That does not work, and the
19
+ failure is not theoretical -- it was reproduced against mcp 2.0.0 before
20
+ this file was written:
21
+
22
+ RuntimeError: Attempted to exit cancel scope in a different task
23
+ than it was entered in
24
+
25
+ Rev. 3 reasoned that the exit stack must live on the MCP *loop*, because
26
+ entering on one loop and exiting on another is undefined. True, but not
27
+ sufficient. anyio binds cancel scopes to the TASK, and
28
+ run_coroutine_threadsafe() creates a NEW TASK for every call. Connecting
29
+ in one task and closing from another is illegal even on the same loop.
30
+
31
+ So a single long-lived _manager() task enters every context, signals
32
+ ready, then parks on an event until shutdown -- the stack unwinds in the
33
+ same task that entered it. Per-call tasks are fine: calling a method on a
34
+ connected client doesn't exit anyone's cancel scope.
35
+
36
+ If you ever see that RuntimeError again, something moved an
37
+ enter/exit across the task boundary. The fix is never "use a different
38
+ loop"; it is "do it inside _manager".
39
+ """
40
+
41
+ import asyncio
42
+ import contextlib
43
+ import json
44
+ import logging
45
+ import threading
46
+ import time
47
+ from typing import Optional
48
+
49
+ from mcp import Client
50
+ from mcp.client.sse import sse_client
51
+ from mcp.client.stdio import StdioServerParameters, stdio_client
52
+ from mcp.client.streamable_http import (
53
+ create_mcp_http_client,
54
+ streamable_http_client,
55
+ )
56
+ from mcp.shared.exceptions import MCPError
57
+
58
+ import config as _harness_config
59
+ from safety.policy_enforcement import TOKEN_CHARS, fragment_end
60
+ from tools.builtin import _net_common
61
+
62
+ logger = logging.getLogger(__name__)
63
+
64
+ # Rev. 1 S12: MCP servers are third-party code and can hang. A generous default
65
+ # beats an indefinite block; individual calls may override.
66
+ DEFAULT_CALL_TIMEOUT_S = 180.0
67
+ CONNECT_TIMEOUT_S = 60.0
68
+ SHUTDOWN_TIMEOUT_S = 15.0
69
+
70
+ # F6 (#64): the WHOLE teardown -- polite close, force-cancel, loop-thread
71
+ # join -- shares this one wall-clock budget, instead of three sequential
72
+ # SHUTDOWN_TIMEOUT_S waits whose worst case hung a quitting harness ~45s.
73
+ # Master value lives in config.py beside the other harness bounds; the
74
+ # re-export here keeps it beside its sibling timeouts and gives tests a
75
+ # single name to shrink.
76
+ TEARDOWN_BUDGET_S = _harness_config.TEARDOWN_BUDGET_S
77
+
78
+ # How much of a structured error payload rides in the error STRING.
79
+ # D23 promises call_tool() returns one error shape, so a server's
80
+ # structured_content on a failure belongs inside that string rather than
81
+ # in a second key every consumer of a dispatch error would have to learn
82
+ # (A32). Bounded because the payload is third-party and the string reaches
83
+ # a model: 500 is room for the {code, retry_after, message} an error
84
+ # payload actually carries, and the cut is visible for the reason
85
+ # _catalog_text's is.
86
+ #
87
+ # The result AS A WHOLE has its own bound, `max_read_chars` (A79); see
88
+ # _normalize.
89
+ MAX_ERROR_DETAIL_CHARS = 500
90
+
91
+ # Per-server, inside the manager. CONNECT_TIMEOUT_S is the caller-side
92
+ # budget for ALL servers together; without a per-server bound one hung
93
+ # handshake spends it and every server after it in the loop is starved of
94
+ # time it never got to use.
95
+ SERVER_CONNECT_TIMEOUT_S = 20.0
96
+
97
+ # How far below the caller-side timeout the protocol-level timeout sits.
98
+ # Both are set, and they do different jobs: read_timeout_seconds cancels
99
+ # the REQUEST at the protocol level, while future.result(timeout=) only
100
+ # unblocks the calling thread and abandons the call locally. The margin
101
+ # makes the protocol one win the race, so a hung server is told to stop
102
+ # rather than merely stopped being waited on, and the caller gets the
103
+ # SDK's specific MCPError instead of a bare TimeoutError.
104
+ #
105
+ # The future timeout is still needed as a backstop for the case the
106
+ # protocol one can't cover: a wedged loop, where no MCP-level response
107
+ # (including the timeout) is coming at all.
108
+ _TIMEOUT_MARGIN_S = 5.0
109
+
110
+ class _TrackClose:
111
+ """Records that one server's session closed cleanly, so a teardown
112
+ that runs out of budget can NAME which server ignored the shutdown
113
+ request instead of reporting an anonymous hang (F6).
114
+
115
+ Recorded only on an unexceptional exit: a session whose __aexit__
116
+ raised, or was interrupted by the force-cancel, did not demonstrably
117
+ close -- and "we stopped waiting for it" is exactly what the
118
+ straggler line means. Attribute access forwards to the real client,
119
+ so list_tools()/call_tool() never notice the wrapper.
120
+ """
121
+
122
+ def __init__(self, inner, name: str, closed: set):
123
+ self._inner = inner
124
+ self._name = name
125
+ self._closed = closed
126
+
127
+ async def __aenter__(self):
128
+ return await self._inner.__aenter__()
129
+
130
+ async def __aexit__(self, *exc):
131
+ try:
132
+ result = await self._inner.__aexit__(*exc)
133
+ except BaseException:
134
+ raise
135
+ self._closed.add(self._name)
136
+ return result
137
+
138
+ def __getattr__(self, item):
139
+ return getattr(self._inner, item)
140
+
141
+
142
+ _loop: Optional[asyncio.AbstractEventLoop] = None
143
+ _thread: Optional[threading.Thread] = None
144
+ _loop_lock = threading.Lock()
145
+
146
+
147
+ def _metered_mcp_client(headers=None, timeout=None, auth=None):
148
+ """The SDK's own MCP client, with the MCP meter's hooks on it (§53).
149
+
150
+ `sse_client`'s `httpx_client_factory` signature, so the one function
151
+ serves both HTTP transports. The SDK builds the client -- its timeouts,
152
+ its redirect rule -- and `event_hooks` is public on an httpx2 client,
153
+ so nothing here re-states what the SDK already decides.
154
+ """
155
+ client = create_mcp_http_client(headers=headers, timeout=timeout,
156
+ auth=auth)
157
+ client.event_hooks = _net_common.mcp_event_hooks()
158
+ return client
159
+
160
+
161
+ def _ensure_loop() -> asyncio.AbstractEventLoop:
162
+ """The one MCP event loop, created on first use."""
163
+ global _loop, _thread
164
+ with _loop_lock:
165
+ if _loop is None:
166
+ _loop = asyncio.new_event_loop()
167
+ _thread = threading.Thread(
168
+ target=_loop.run_forever, name="mcp-loop", daemon=True)
169
+ _thread.start()
170
+ logger.debug("Started MCP event loop thread.")
171
+ return _loop
172
+
173
+
174
+ def _shutdown_loop(join_timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
175
+ global _loop, _thread
176
+ with _loop_lock:
177
+ if _loop is None:
178
+ return
179
+ _loop.call_soon_threadsafe(_loop.stop)
180
+ if _thread is not None:
181
+ _thread.join(timeout=join_timeout)
182
+ if _thread.is_alive():
183
+ logger.warning("MCP loop thread did not stop within %.1fs.",
184
+ join_timeout)
185
+ _loop = None
186
+ _thread = None
187
+
188
+
189
+ def _detail(structured) -> str:
190
+ """A structured payload as one bounded line, for the error string.
191
+
192
+ default=str so a payload holding something JSON cannot carry is still
193
+ reported rather than raising inside the error path -- D23's promise
194
+ that this module returns one error shape has to mean always, which is
195
+ the same argument the broad except in call_tool() makes.
196
+ """
197
+ try:
198
+ rendered = json.dumps(structured, default=str, sort_keys=True)
199
+ except Exception:
200
+ rendered = repr(structured)
201
+ rendered = " ".join(rendered.split())
202
+ if len(rendered) <= MAX_ERROR_DETAIL_CHARS:
203
+ return rendered
204
+ return rendered[:MAX_ERROR_DETAIL_CHARS - 1].rstrip() + "\u2026"
205
+
206
+
207
+ def _cut(text: str, limit: int) -> str:
208
+ """The first *limit* characters of *text*, less a word the cut split.
209
+
210
+ The redactor runs after this, on the dispatch path, and cannot match
211
+ half a credential. So when the character past the cut is a token
212
+ character, the token-character run the cut ends inside goes too: the
213
+ rule A72 made for a shell session's dropped middle. A cut that fell
214
+ between two words drops nothing more.
215
+ """
216
+ if len(text) <= limit:
217
+ return text
218
+ kept = text[:limit]
219
+ if text[limit] in TOKEN_CHARS:
220
+ kept = kept[:fragment_end(kept)]
221
+ return kept
222
+
223
+
224
+ def _json_chars(structured) -> Optional[int]:
225
+ """How many characters *structured* takes as JSON, or None when it
226
+ cannot be rendered -- which _normalize reads as too large to keep,
227
+ since nothing can say how large it is."""
228
+ try:
229
+ return len(json.dumps(structured, default=str, ensure_ascii=False))
230
+ except Exception:
231
+ return None
232
+
233
+
234
+ def _repeats(structured, text: str) -> bool:
235
+ """Whether *structured* is the server's text over again.
236
+
237
+ The SDK's own server sends a tool that returns a string as that text
238
+ AND as `{"result": <the text>}`, and a typed return as the JSON in
239
+ both places. A dropped copy of the text is no loss, and the note says
240
+ so, so the model does not call again for something it already has.
241
+ """
242
+ if structured == {"result": text}:
243
+ return True
244
+ try:
245
+ return json.loads(text) == structured
246
+ except Exception:
247
+ return False
248
+
249
+
250
+ def _normalize(result, tool_name: str = "") -> dict:
251
+ """CallToolResult -> the plain dict shape every other tool handler
252
+ returns (D23).
253
+
254
+ Fixing this at the producer rather than the consumer is the whole
255
+ point. Downstream, check_output_policy() calls result.get(key) and
256
+ would raise AttributeError on a pydantic model -- meaning MCP output,
257
+ the output most likely to come from code the user didn't write, is
258
+ exactly the output that would bypass secret redaction. And
259
+ memory.add_tool_result() would str() a pydantic repr into the thread.
260
+
261
+ MCP signals tool failure IN BAND via is_error rather than by raising,
262
+ so it maps onto the same {"error": ...} convention _run() already
263
+ understands for ToolCallDenied and disallowed tools. No new error
264
+ channel, no special-casing in the loop.
265
+
266
+ Keys are 'content' and 'result' deliberately, though NOT for the
267
+ reason this comment used to give. It said both were in
268
+ safety/policy_enforcement.py's `_SCANNED_KEYS`, so MCP output was
269
+ secret-redacted by the existing layer with no change to it. That set
270
+ no longer exists (#47): check_output_policy scans every value, so any
271
+ key would now be covered. Choosing these two is about matching the
272
+ shape every other handler returns (D23), not about clearing a
273
+ redaction bar.
274
+
275
+ Worth keeping as a caution rather than deleting: this docstring is
276
+ the evidence that authors DID read the allowlist as a contract and
277
+ write to it. Two older built-ins returned `results` and never
278
+ satisfied it, which is the defect #47 records.
279
+
280
+ v2 renamed these fields to snake_case (.content/.structured_content/
281
+ .is_error); §17's sketch reads the v1 camelCase spellings and would
282
+ silently see is_error as always-False against v2.
283
+
284
+ THE RESULT IS BOUNDED HERE, AS A WHOLE, AT `max_read_chars` (A79).
285
+ Every other producer of third-party text bounds what it hands on, and
286
+ this one handed on anything: 10 MB of text, of structured content or
287
+ of an error message went through whole, into the thread and the
288
+ model's context, behind a redaction pass that took 1.2-2.5 s over it.
289
+ The server's text is cut at the bound with a note giving the size it
290
+ had. A structured payload is kept whole if it fits in what the text
291
+ left of the bound, and otherwise dropped with a note -- never cut,
292
+ since a JSON document cut short can read as complete. A server that
293
+ follows the MCP spec sends structured output as text as well, so the
294
+ text usually carries what was dropped, and the note says when it was
295
+ a repeat (see `_repeats`). The bound is `max_read_chars`
296
+ because it is already how much one read is, and the compaction
297
+ headroom check measures a read against it.
298
+ """
299
+ bound = int(_harness_config.MAX_READ_CHARS)
300
+ blocks = getattr(result, "content", None) or []
301
+ kept, dropped = [], []
302
+ for block in blocks:
303
+ kind = getattr(block, "type", None) or "unknown"
304
+ if kind == "text":
305
+ value = getattr(block, "text", None)
306
+ if value:
307
+ kept.append(value)
308
+ # AN EMPTY TEXT BLOCK HAS NOTHING TO DROP. It is filtered out
309
+ # of the join either way, but counting it as dropped content
310
+ # made the placeholder contradict itself -- `text("")` came
311
+ # back as "[non-text MCP content: text]", reporting the kind
312
+ # as non-text when the kind is text.
313
+ continue
314
+ dropped.append(kind)
315
+
316
+ full = "\n".join(kept)
317
+ text = _cut(full, bound)
318
+ sent, shown = len(full), len(text)
319
+ if dropped:
320
+ # APPENDED, NOT SUBSTITUTED (A32). Non-text blocks (images,
321
+ # embedded resources) are still dropped -- the harness has no
322
+ # multimodal tool-result path, and inventing one here is scope the
323
+ # rest of the design can't carry. What changed is WHEN the
324
+ # disclosure happens: the placeholder used to fire only when NO
325
+ # text survived, so a result carrying text AND non-text dropped
326
+ # the non-text silently, and "Chart generated:" with no chart and
327
+ # no note is a result the model will answer from. CallToolResult.
328
+ # content is a REQUIRED list of mixed block types on the installed
329
+ # SDK, so that shape is first-class in the protocol rather than
330
+ # hypothetical.
331
+ kinds = ", ".join(sorted(set(dropped)))
332
+ note = f"[non-text MCP content: {kinds}]"
333
+ text = f"{text}\n{note}" if text else note
334
+ # ONE WARNING NAMING THE TOOL AND WHAT CHANGED, which is the rule
335
+ # #49 was filed to establish and which this function broke on all
336
+ # three of its dropping paths. The tool name is a PARAMETER
337
+ # because this function could not name the tool -- it took the
338
+ # result alone, so the rule was unsatisfiable here as written.
339
+ logger.warning(
340
+ "MCP tool %s returned %d non-text block(s) (%s); this harness "
341
+ "has no multimodal tool-result path, so they were dropped and "
342
+ "the result says so in band.",
343
+ tool_name or "<unknown>", len(dropped), kinds)
344
+
345
+ if shown < sent:
346
+ # After the non-text note, so neither note is what the cut takes.
347
+ note = (f"[MCP result cut: the server sent {sent:,} characters of "
348
+ f"text, and the {shown:,} shown end at the last word break "
349
+ f"inside the bound, max_read_chars ({bound:,})]")
350
+ text = f"{text}\n{note}" if text else note
351
+ logger.warning(
352
+ "MCP tool %s returned %d characters of text; it was cut to %d "
353
+ "(max_read_chars is %d) and the result says so in band.",
354
+ tool_name or "<unknown>", sent, shown, bound)
355
+
356
+ structured = getattr(result, "structured_content", None)
357
+ if getattr(result, "is_error", False):
358
+ message = text or "MCP tool call failed"
359
+ if structured is not None:
360
+ # D23's ONE error shape, not a second key (A32): a server
361
+ # reporting {code: 429, retry_after: 30} used to lose it
362
+ # entirely, so the one thing that would have explained the
363
+ # failure was the one thing dropped.
364
+ detail = _detail(structured)
365
+ message = f"{message} (server detail: {detail})"
366
+ logger.warning(
367
+ "MCP tool %s failed with a structured payload; it is "
368
+ "folded into the error string: %s",
369
+ tool_name or "<unknown>", detail)
370
+ return {"error": message}
371
+
372
+ if structured is not None:
373
+ size, room = _json_chars(structured), bound - shown
374
+ if size is None or size > room:
375
+ if size is None:
376
+ why = "it could not be rendered as JSON to be measured"
377
+ else:
378
+ why = (f"it is {size:,} characters as JSON, and the text "
379
+ f"left {room:,} of the bound, max_read_chars "
380
+ f"({bound:,})")
381
+ if _repeats(structured, full):
382
+ why += "; it repeats the server's text"
383
+ note = f"[MCP structured result dropped: {why}]"
384
+ text = f"{text}\n{note}" if text else note
385
+ logger.warning(
386
+ "MCP tool %s returned structured content of %s characters "
387
+ "with %d left of max_read_chars; it was dropped and the "
388
+ "result says so in band.",
389
+ tool_name or "<unknown>",
390
+ "unmeasurable" if size is None else size, room)
391
+ structured = None
392
+
393
+ out = {"content": text}
394
+ if structured is not None:
395
+ out["result"] = structured
396
+ return out
397
+
398
+
399
+ class MCPClient:
400
+ """Connects to configured MCP servers and exposes a synchronous
401
+ call_tool() that looks completely ordinary to registry.dispatch()."""
402
+
403
+ def __init__(self, server_configs: dict):
404
+ # Set, and inspectable (§17 AC1). Rev. 1 omitted this assignment
405
+ # entirely -- a real bug (C10) that made every later method fail
406
+ # on a missing attribute.
407
+ self.server_configs = server_configs
408
+ self.clients: dict = {}
409
+ self.failures: dict = {} # server name -> why it isn't usable
410
+ self._closed: set = set() # servers whose session closed cleanly
411
+ # F8 (#63): the catalogue gathered during connect, inside that
412
+ # call's per-server timeout. Registration serves from here --
413
+ # which removes MCP's one bridge call with NO protocol timeout,
414
+ # and the window where a slow post-connect listing burned its
415
+ # own 30s. A miss falls back to fetching.
416
+ self._catalogs: dict = {}
417
+ self._ready: Optional[asyncio.Event] = None
418
+ self._shutdown: Optional[asyncio.Event] = None
419
+ self._done: Optional[asyncio.Event] = None
420
+ self._task = None
421
+
422
+ # -- connection ------------------------------------------------------
423
+
424
+ def _transport_for(self, cfg):
425
+ """SDK object for one server. v2 collapsed v1's stdio-vs-HTTP
426
+ branch: Client() takes a Transport, a URL string, or an in-process
427
+ server object, so this returns whichever and Client sorts it out."""
428
+ if cfg.transport == "stdio":
429
+ return stdio_client(StdioServerParameters(
430
+ command=cfg.command,
431
+ args=[str(a) for a in cfg.args],
432
+ env=cfg.env or None,
433
+ cwd=cfg.cwd,
434
+ ))
435
+ if cfg.transport == "sse":
436
+ # SSE must ALWAYS build its own transport: a bare URL string
437
+ # means STREAMABLE HTTP to Client(), which is exactly the
438
+ # silent misconnection #62 records. Headers go straight to
439
+ # the SDK (its signature takes `headers=`), through the same
440
+ # create_mcp_http_client defaults -- so an Authorization
441
+ # header authenticates here too, never discarded (M19's
442
+ # property holds on both HTTP transports).
443
+ #
444
+ # ROADMAP_v3 §53: with the MCP meter on, the SDK's own factory
445
+ # builds the client and the meter's hooks go on it, so its
446
+ # timeouts are the SDK's and only the counting is ours.
447
+ if _net_common.MCP.enabled():
448
+ return sse_client(
449
+ cfg.url,
450
+ headers=dict(cfg.headers) or None,
451
+ httpx_client_factory=_metered_mcp_client,
452
+ )
453
+ return sse_client(
454
+ cfg.url,
455
+ headers=dict(cfg.headers) or None,
456
+ )
457
+ if cfg.transport == "http":
458
+ # `headers` was parsed into ServerConfig and then never used:
459
+ # a bare URL carries none of them, so a server configured with
460
+ # an Authorization header connected UNAUTHENTICATED, with
461
+ # nothing indicating they had been discarded. In v2 headers
462
+ # live on the httpx2 client, and the SDK ships the helper that
463
+ # applies its own MCP defaults alongside them -- so this uses
464
+ # that rather than hand-building a client and losing the
465
+ # SSE-friendly timeouts. Without headers the SDK builds its own
466
+ # client, exactly as Client() does for a bare URL.
467
+ #
468
+ # NEVER a bare URL now, even without headers (batch 208): mcp
469
+ # 2.3.0 fails a call whose one server-sent event exceeds
470
+ # `max_sse_event_size`, and a bare URL takes the SDK's 1 MiB,
471
+ # which a streamed screenshot passes. config.yaml's
472
+ # `mcp_max_event_bytes` is the ceiling, read per connection. It
473
+ # bounds STREAMED answers only: one sent as plain JSON is read
474
+ # whole (CONFIG_ARCHITECTURE.md has the measurement). The legacy
475
+ # "sse" branch above keeps the SDK's fixed 1 MiB: `sse_client`
476
+ # takes no size.
477
+ #
478
+ # ROADMAP_v3 §53: with the MCP meter on there is ALWAYS a client
479
+ # of ours, headers or not, because the hooks have to be on it.
480
+ # Built by the SDK's helper either way, so its timeouts hold.
481
+ if _net_common.MCP.enabled():
482
+ http_client = _metered_mcp_client(
483
+ headers=dict(cfg.headers) or None)
484
+ elif cfg.headers:
485
+ http_client = create_mcp_http_client(headers=dict(cfg.headers))
486
+ else:
487
+ http_client = None
488
+ return streamable_http_client(
489
+ cfg.url,
490
+ http_client=http_client,
491
+ max_sse_event_size=_harness_config.MCP_MAX_EVENT_BYTES,
492
+ )
493
+ raise ValueError(cfg.error or "unusable server configuration")
494
+
495
+ @staticmethod
496
+ def _reason(e: BaseException, budget: Optional[float] = None) -> str:
497
+ """Why a server is unusable, in one string for BOTH consumers.
498
+
499
+ Batch 121, from the owner's log: `MCP server 'joplin' failed to
500
+ connect: ` and nothing after the colon. The per-server
501
+ asyncio.timeout raises TimeoutError, whose str() is "" -- so the
502
+ %s below rendered nothing, and the one message that explains a
503
+ silent MCP named no cause at all.
504
+
505
+ It was also TWO strings: `failures` carried the exception type and
506
+ the log line did not, so the better of the two never reached the
507
+ place a user looks first. One copy now, and the timeout names its
508
+ budget because "it timed out" without a duration leaves the
509
+ reader unable to tell a dead server from a slow one.
510
+ """
511
+ text = str(e)
512
+ if text:
513
+ return f"{type(e).__name__}: {text}"
514
+ if isinstance(e, TimeoutError) and budget is not None:
515
+ return f"{type(e).__name__} (no handshake within {budget}s)"
516
+ return type(e).__name__
517
+
518
+ async def _manager(self):
519
+ """Owns the AsyncExitStack for the whole process lifetime, in ONE
520
+ task. See the module docstring -- this shape is required, not
521
+ stylistic."""
522
+ try:
523
+ async with contextlib.AsyncExitStack() as stack:
524
+ for name, cfg in self.server_configs.items():
525
+ if cfg.disabled:
526
+ logger.info("MCP server %r is disabled; skipping.", name)
527
+ continue
528
+ try:
529
+ # PER-SERVER bound, not just the caller's blanket
530
+ # one. v2's list_tools() takes no
531
+ # read_timeout_seconds, so a server that spawns and
532
+ # then never answers the handshake would otherwise
533
+ # consume the whole shared connect budget and starve
534
+ # every server after it in this loop.
535
+ async with asyncio.timeout(SERVER_CONNECT_TIMEOUT_S):
536
+ client = await stack.enter_async_context(
537
+ _TrackClose(
538
+ Client(self._transport_for(cfg)), name,
539
+ self._closed)
540
+ )
541
+ # Validation is by connection (§17 decision G):
542
+ # a server that connects AND lists its tools is
543
+ # usable. The listing IS registration's
544
+ # catalogue (F8): cached below, served from,
545
+ # never fetched a second time.
546
+ tools = await client.list_tools()
547
+ self.clients[name] = client
548
+ self._catalogs[name] = list(tools.tools)
549
+ logger.info("MCP server %r connected (%d tools).",
550
+ name, len(tools.tools))
551
+ except Exception as e:
552
+ # One unreachable server must never take down the
553
+ # others, or a single stale entry makes the whole
554
+ # harness unusable. §17's sketch had no try/except
555
+ # here at all.
556
+ why = self._reason(e, SERVER_CONNECT_TIMEOUT_S)
557
+ self.failures[name] = why
558
+ logger.warning("MCP server %r failed to connect: %s",
559
+ name, why)
560
+ self._ready.set()
561
+ await self._shutdown.wait()
562
+ except Exception:
563
+ logger.exception("MCP manager task failed")
564
+ if self._ready is not None and not self._ready.is_set():
565
+ self._ready.set()
566
+ finally:
567
+ if self._done is not None:
568
+ self._done.set()
569
+
570
+ def connect_all(self, timeout: float = CONNECT_TIMEOUT_S) -> None:
571
+ """Connect every configured server. Synchronous, callable from
572
+ ordinary startup code; the bridge does the rest."""
573
+ if not self.server_configs:
574
+ return
575
+ if self._task is not None:
576
+ # #219, batch 213, the owner's choice of raising over tearing
577
+ # down first. Every attribute below is rebound, so a second call
578
+ # used to abandon the first generation's manager parked on a
579
+ # `_shutdown` nothing could set any more -- its child processes
580
+ # with it, and no straggler warning. Nothing reconnects today
581
+ # (one call site, main.py); F7's runtime /mcp would, and it has
582
+ # to disconnect on purpose.
583
+ raise RuntimeError(
584
+ "connect_all() on an MCP client that is already connected; "
585
+ "call disconnect_all() first")
586
+ loop = _ensure_loop()
587
+
588
+ async def _start():
589
+ self._ready = asyncio.Event()
590
+ self._shutdown = asyncio.Event()
591
+ self._done = asyncio.Event()
592
+ self._task = loop.create_task(self._manager())
593
+ await self._ready.wait()
594
+
595
+ started = asyncio.run_coroutine_threadsafe(_start(), loop)
596
+ try:
597
+ started.result(timeout=timeout)
598
+ except Exception:
599
+ # A timeout here used to abandon the manager permanently. It
600
+ # would still be parked mid-connect holding every child process
601
+ # already spawned, and NOTHING could close it: disconnect_all()
602
+ # waits on _done, which a stuck manager never sets. So one hung
603
+ # server orphaned every other server's subprocess -- the exact
604
+ # inversion of this file's "one unreachable server must never
605
+ # take down the others" invariant.
606
+ #
607
+ # `started` IS RELEASED TOO (A33), and it is a different object
608
+ # from the manager: _start() is still awaiting _ready when the
609
+ # caller's budget runs out, and the two lines below stop the
610
+ # loop out from under it. Left pending, asyncio reports "Task
611
+ # was destroyed but it is pending!" through its own logger at
612
+ # whatever moment the GC gets to it -- and the TUI's
613
+ # TranscriptLogHandler is on the ROOT logger, so that line can
614
+ # surface in a user's transcript naming nothing and
615
+ # attributable to nothing. Cancelled FIRST, while the loop is
616
+ # still running to deliver it; _cancel_manager() needs the
617
+ # same loop alive and _shutdown_loop() is what ends it.
618
+ started.cancel()
619
+ self._cancel_manager()
620
+ self.clients.clear()
621
+ self._catalogs.clear()
622
+ self._task = None
623
+ _shutdown_loop()
624
+ raise
625
+
626
+ # -- calling ---------------------------------------------------------
627
+
628
+ def list_tools(self, server_name: str, timeout: float = 30.0):
629
+ """The server's tool catalogue. Serves the connect-time cache
630
+ (F8) -- the one MCP call that had no protocol timeout -- and
631
+ crosses the bridge only on a miss. A copy comes back, so a
632
+ caller cannot mutate the cache."""
633
+ cached = self._catalogs.get(server_name)
634
+ if cached is not None:
635
+ return list(cached)
636
+ client = self.clients[server_name]
637
+ fut = asyncio.run_coroutine_threadsafe(client.list_tools(), _ensure_loop())
638
+ return fut.result(timeout=timeout).tools
639
+
640
+ def call_tool(self, server_name: str, tool_name: str, params: dict,
641
+ timeout: float = DEFAULT_CALL_TIMEOUT_S) -> dict:
642
+ """The synchronous entry point every ToolSpec.handler calls.
643
+
644
+ Looks ordinary to registry.dispatch() regardless of whether the
645
+ caller sits on Textual's main loop, a worker thread, or a plain
646
+ CLI script -- the bridge is what makes caller context irrelevant.
647
+
648
+ Returns a plain dict, never a CallToolResult (D23, §17 AC6).
649
+ """
650
+ client = self.clients.get(server_name)
651
+ if client is None:
652
+ reason = self.failures.get(server_name, "not connected")
653
+ return {"error": f"MCP server {server_name!r} is unavailable: {reason}"}
654
+
655
+ # ROADMAP_v3 §53 (IO11). Admitted HERE, before anything is sent, and
656
+ # never in the HTTP hooks: a refusal raised inside the SDK would
657
+ # surface in its background writer and read as a timeout. Only the
658
+ # servers the meter can see are asked -- a "stdio" server's traffic
659
+ # is its own process's, and IO5 says so rather than pretending.
660
+ cfg = self.server_configs.get(server_name)
661
+ if getattr(cfg, "transport", None) in ("http", "sse"):
662
+ try:
663
+ _net_common.MCP.admit(_net_common.mcp_call_bytes(params))
664
+ except _net_common.NetworkLimitReached as e:
665
+ return {"error": e.reason}
666
+
667
+ loop = _ensure_loop()
668
+ protocol_timeout = max(1.0, timeout - _TIMEOUT_MARGIN_S)
669
+ coro = client.call_tool(tool_name, params,
670
+ read_timeout_seconds=protocol_timeout)
671
+ future = asyncio.run_coroutine_threadsafe(coro, loop)
672
+ try:
673
+ return _normalize(future.result(timeout=timeout), tool_name)
674
+ except MCPError as e:
675
+ # v2 raises for protocol-level failures -- including timeout,
676
+ # which is code -32001 -- where v1 reported everything in
677
+ # band. Map onto the same {"error": ...} convention so the
678
+ # loop keeps exactly one error shape to understand.
679
+ return {"error": f"MCP call failed: {e}"}
680
+ except TimeoutError:
681
+ # The protocol timeout should have fired first. Reaching here
682
+ # means the loop itself is wedged; cancel so the coroutine
683
+ # can't outlive the call.
684
+ future.cancel()
685
+ return {"error": f"MCP tool {tool_name!r} timed out after {timeout}s"}
686
+ except Exception as e:
687
+ # LAST, so the two specific branches above keep their handling
688
+ # (notably future.cancel()). MCPError is not the only thing v2
689
+ # raises: an outputSchema violation surfaces as a bare
690
+ # RuntimeError and a malformed payload as a pydantic
691
+ # ValidationError. dispatch() has no handler-exception catch
692
+ # and _run() catches only ToolCallDenied, so anything escaping
693
+ # here takes down the whole conversation -- or all ten research
694
+ # passes -- on one buggy third-party server. D23 promises this
695
+ # function returns ONE error shape; that has to mean always.
696
+ logger.debug("MCP call raised", exc_info=True)
697
+ return {"error": f"MCP call failed: {type(e).__name__}: {e}"}
698
+
699
+ # -- shutdown --------------------------------------------------------
700
+
701
+ def _cancel_manager(self, timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
702
+ """Force the manager task to unwind its exit stack.
703
+
704
+ Cancellation is the ONLY way to close the stack from outside the
705
+ graceful path, and it works for the same reason the graceful path
706
+ does: CancelledError is raised inside the manager's `async with`,
707
+ so __aexit__ runs in the task that entered it. Calling aclose()
708
+ from any other task is the cancel-scope error this module's
709
+ docstring is about.
710
+ """
711
+ task, loop = self._task, _loop
712
+ if task is None or loop is None:
713
+ return
714
+ try:
715
+ async def _cancel():
716
+ task.cancel()
717
+ if self._done is not None:
718
+ await self._done.wait()
719
+ asyncio.run_coroutine_threadsafe(_cancel(), loop).result(timeout=timeout)
720
+ except Exception as e:
721
+ logger.warning("MCP manager task did not cancel cleanly: %s", e)
722
+
723
+ def disconnect_all(self, timeout: float = None) -> None:
724
+ """Close every session and stop the loop thread.
725
+
726
+ Not tidiness: stdio servers are child processes THIS harness
727
+ spawned. The daemon thread dies at interpreter exit without
728
+ unwinding the stack, and the failure mode is orphaned
729
+ subprocesses accumulating across sessions.
730
+
731
+ F6 (#64): `timeout` is ONE budget for everything -- the polite
732
+ close gets its first slice, force-cancel takes what remains
733
+ (minus a join reserve), the loop-thread join takes the rest. It
734
+ used to be three sequential SHUTDOWN_TIMEOUT_S waits, so one
735
+ wedged server hung a quitting harness ~45s and Ctrl+C paid all
736
+ of it. Servers that never confirmed a clean close by expiry are
737
+ named in a WARNING.
738
+ """
739
+ budget = TEARDOWN_BUDGET_S if timeout is None else timeout
740
+ if self._task is None or _loop is None:
741
+ _shutdown_loop()
742
+ return
743
+
744
+ started = time.monotonic()
745
+
746
+ def remaining() -> float:
747
+ return max(0.0, budget - (time.monotonic() - started))
748
+
749
+ graceful = False
750
+ try:
751
+ async def _stop():
752
+ self._shutdown.set()
753
+ await self._done.wait()
754
+ asyncio.run_coroutine_threadsafe(_stop(), _loop).result(
755
+ timeout=max(1.0, budget * 0.6))
756
+ graceful = True
757
+ except Exception as e:
758
+ logger.warning("MCP shutdown did not complete cleanly within "
759
+ "%.1fs of the %.1fs teardown budget: %s",
760
+ max(1.0, budget * 0.6), budget, e)
761
+ if not graceful:
762
+ # The stack is still open and the children are still ours.
763
+ # Asking politely didn't work, so cancel -- otherwise this
764
+ # returns having reaped nothing while reporting only a warning.
765
+ self._cancel_manager(timeout=max(1.0, remaining() - 1.0))
766
+
767
+ stragglers = sorted(set(self.clients) - self._closed)
768
+ if stragglers:
769
+ logger.warning(
770
+ "MCP server(s) %s did not confirm a clean close within the "
771
+ "%.1fs teardown budget; their child processes may outlive "
772
+ "this session.", ", ".join(stragglers), budget)
773
+
774
+ self.clients.clear()
775
+ self._catalogs.clear()
776
+ # #219. Keyed by server name, so a clean close kept from this
777
+ # generation would answer for the next one's straggler check.
778
+ self._closed.clear()
779
+ self._task = None
780
+ _shutdown_loop(join_timeout=max(0.5, remaining()))