@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,499 +1,733 @@
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 logging
44
- import threading
45
- import time
46
- from typing import Optional
47
-
48
- import config as _harness_config
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, streamable_http_client,
54
- )
55
- from mcp.shared.exceptions import MCPError
56
-
57
- logger = logging.getLogger(__name__)
58
-
59
- # Rev. 1 S12: MCP servers are third-party code and can hang. A generous default
60
- # beats an indefinite block; individual calls may override.
61
- DEFAULT_CALL_TIMEOUT_S = 180.0
62
- CONNECT_TIMEOUT_S = 60.0
63
- SHUTDOWN_TIMEOUT_S = 15.0
64
-
65
- # F6 (#64): the WHOLE teardown -- polite close, force-cancel, loop-thread
66
- # join -- shares this one wall-clock budget, instead of three sequential
67
- # SHUTDOWN_TIMEOUT_S waits whose worst case hung a quitting harness ~45s.
68
- # Master value lives in config.py beside the other harness bounds; the
69
- # re-export here keeps it beside its sibling timeouts and gives tests a
70
- # single name to shrink.
71
- TEARDOWN_BUDGET_S = _harness_config.TEARDOWN_BUDGET_S
72
-
73
- # Per-server, inside the manager. CONNECT_TIMEOUT_S is the caller-side
74
- # budget for ALL servers together; without a per-server bound one hung
75
- # handshake spends it and every server after it in the loop is starved of
76
- # time it never got to use.
77
- SERVER_CONNECT_TIMEOUT_S = 20.0
78
-
79
- # How far below the caller-side timeout the protocol-level timeout sits.
80
- # Both are set, and they do different jobs: read_timeout_seconds cancels
81
- # the REQUEST at the protocol level, while future.result(timeout=) only
82
- # unblocks the calling thread and abandons the call locally. The margin
83
- # makes the protocol one win the race, so a hung server is told to stop
84
- # rather than merely stopped being waited on, and the caller gets the
85
- # SDK's specific MCPError instead of a bare TimeoutError.
86
- #
87
- # The future timeout is still needed as a backstop for the case the
88
- # protocol one can't cover: a wedged loop, where no MCP-level response
89
- # (including the timeout) is coming at all.
90
- _TIMEOUT_MARGIN_S = 5.0
91
-
92
- class _TrackClose:
93
- """Records that one server's session closed cleanly, so a teardown
94
- that runs out of budget can NAME which server ignored the shutdown
95
- request instead of reporting an anonymous hang (F6).
96
-
97
- Recorded only on an unexceptional exit: a session whose __aexit__
98
- raised, or was interrupted by the force-cancel, did not demonstrably
99
- close -- and "we stopped waiting for it" is exactly what the
100
- straggler line means. Attribute access forwards to the real client,
101
- so list_tools()/call_tool() never notice the wrapper.
102
- """
103
-
104
- def __init__(self, inner, name: str, closed: set):
105
- self._inner = inner
106
- self._name = name
107
- self._closed = closed
108
-
109
- async def __aenter__(self):
110
- return await self._inner.__aenter__()
111
-
112
- async def __aexit__(self, *exc):
113
- try:
114
- result = await self._inner.__aexit__(*exc)
115
- except BaseException:
116
- raise
117
- self._closed.add(self._name)
118
- return result
119
-
120
- def __getattr__(self, item):
121
- return getattr(self._inner, item)
122
-
123
-
124
- _loop: Optional[asyncio.AbstractEventLoop] = None
125
- _thread: Optional[threading.Thread] = None
126
- _loop_lock = threading.Lock()
127
-
128
-
129
- def _ensure_loop() -> asyncio.AbstractEventLoop:
130
- """The one MCP event loop, created on first use."""
131
- global _loop, _thread
132
- with _loop_lock:
133
- if _loop is None:
134
- _loop = asyncio.new_event_loop()
135
- _thread = threading.Thread(
136
- target=_loop.run_forever, name="mcp-loop", daemon=True)
137
- _thread.start()
138
- logger.debug("Started MCP event loop thread.")
139
- return _loop
140
-
141
-
142
- def _shutdown_loop(join_timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
143
- global _loop, _thread
144
- with _loop_lock:
145
- if _loop is None:
146
- return
147
- _loop.call_soon_threadsafe(_loop.stop)
148
- if _thread is not None:
149
- _thread.join(timeout=join_timeout)
150
- if _thread.is_alive():
151
- logger.warning("MCP loop thread did not stop within %.1fs.",
152
- join_timeout)
153
- _loop = None
154
- _thread = None
155
-
156
-
157
- def _normalize(result) -> dict:
158
- """CallToolResult -> the plain dict shape every other tool handler
159
- returns (D23).
160
-
161
- Fixing this at the producer rather than the consumer is the whole
162
- point. Downstream, check_output_policy() calls result.get(key) and
163
- would raise AttributeError on a pydantic model -- meaning MCP output,
164
- the output most likely to come from code the user didn't write, is
165
- exactly the output that would bypass secret redaction. And
166
- memory.add_tool_result() would str() a pydantic repr into the thread.
167
-
168
- MCP signals tool failure IN BAND via is_error rather than by raising,
169
- so it maps onto the same {"error": ...} convention _run() already
170
- understands for ToolCallDenied and disallowed tools. No new error
171
- channel, no special-casing in the loop.
172
-
173
- Keys are 'content' and 'result' deliberately, though NOT for the
174
- reason this comment used to give. It said both were in
175
- safety/policy_enforcement.py's `_SCANNED_KEYS`, so MCP output was
176
- secret-redacted by the existing layer with no change to it. That set
177
- no longer exists (#47): check_output_policy scans every value, so any
178
- key would now be covered. Choosing these two is about matching the
179
- shape every other handler returns (D23), not about clearing a
180
- redaction bar.
181
-
182
- Worth keeping as a caution rather than deleting: this docstring is
183
- the evidence that authors DID read the allowlist as a contract and
184
- write to it. Two older built-ins returned `results` and never
185
- satisfied it, which is the defect #47 records.
186
-
187
- v2 renamed these fields to snake_case (.content/.structured_content/
188
- .is_error); §17's sketch reads the v1 camelCase spellings and would
189
- silently see is_error as always-False against v2.
190
- """
191
- blocks = getattr(result, "content", None) or []
192
- text = "\n".join(
193
- b.text for b in blocks
194
- if getattr(b, "type", None) == "text" and getattr(b, "text", None)
195
- )
196
- if not text and blocks:
197
- # Non-text blocks (images, embedded resources) are dropped to a
198
- # placeholder: the harness has no multimodal tool-result path, and
199
- # inventing one here is scope the rest of the design can't carry.
200
- kinds = sorted({getattr(b, "type", "unknown") for b in blocks})
201
- text = f"[non-text MCP content: {', '.join(kinds)}]"
202
-
203
- if getattr(result, "is_error", False):
204
- return {"error": text or "MCP tool call failed"}
205
-
206
- out = {"content": text}
207
- structured = getattr(result, "structured_content", None)
208
- if structured is not None:
209
- out["result"] = structured
210
- return out
211
-
212
-
213
- class MCPClient:
214
- """Connects to configured MCP servers and exposes a synchronous
215
- call_tool() that looks completely ordinary to registry.dispatch()."""
216
-
217
- def __init__(self, server_configs: dict):
218
- # Set, and inspectable (§17 AC1). Rev. 1 omitted this assignment
219
- # entirely -- a real bug (C10) that made every later method fail
220
- # on a missing attribute.
221
- self.server_configs = server_configs
222
- self.clients: dict = {}
223
- self.failures: dict = {} # server name -> why it isn't usable
224
- self._closed: set = set() # servers whose session closed cleanly
225
- # F8 (#63): the catalogue gathered during connect, inside that
226
- # call's per-server timeout. Registration serves from here --
227
- # which removes MCP's one bridge call with NO protocol timeout,
228
- # and the window where a slow post-connect listing burned its
229
- # own 30s. A miss falls back to fetching.
230
- self._catalogs: dict = {}
231
- self._ready: Optional[asyncio.Event] = None
232
- self._shutdown: Optional[asyncio.Event] = None
233
- self._done: Optional[asyncio.Event] = None
234
- self._task = None
235
-
236
- # -- connection ------------------------------------------------------
237
-
238
- def _transport_for(self, cfg):
239
- """SDK object for one server. v2 collapsed v1's stdio-vs-HTTP
240
- branch: Client() takes a Transport, a URL string, or an in-process
241
- server object, so this returns whichever and Client sorts it out."""
242
- if cfg.transport == "stdio":
243
- return stdio_client(StdioServerParameters(
244
- command=cfg.command,
245
- args=[str(a) for a in cfg.args],
246
- env=cfg.env or None,
247
- cwd=cfg.cwd,
248
- ))
249
- if cfg.transport == "sse":
250
- # SSE must ALWAYS build its own transport: a bare URL string
251
- # means STREAMABLE HTTP to Client(), which is exactly the
252
- # silent misconnection #62 records. Headers go straight to
253
- # the SDK (its signature takes `headers=`), through the same
254
- # create_mcp_http_client defaults -- so an Authorization
255
- # header authenticates here too, never discarded (M19's
256
- # property holds on both HTTP transports).
257
- return sse_client(
258
- cfg.url,
259
- headers=dict(cfg.headers) or None,
260
- )
261
- if cfg.transport == "http":
262
- if not cfg.headers:
263
- return cfg.url
264
- # `headers` was parsed into ServerConfig and then never used:
265
- # a bare URL carries none of them, so a server configured with
266
- # an Authorization header connected UNAUTHENTICATED, with
267
- # nothing indicating they had been discarded. In v2 headers
268
- # live on the httpx2 client, and the SDK ships the helper that
269
- # applies its own MCP defaults alongside them -- so this uses
270
- # that rather than hand-building a client and losing the
271
- # SSE-friendly timeouts.
272
- return streamable_http_client(
273
- cfg.url,
274
- http_client=create_mcp_http_client(headers=dict(cfg.headers)),
275
- )
276
- raise ValueError(cfg.error or "unusable server configuration")
277
-
278
- async def _manager(self):
279
- """Owns the AsyncExitStack for the whole process lifetime, in ONE
280
- task. See the module docstring -- this shape is required, not
281
- stylistic."""
282
- try:
283
- async with contextlib.AsyncExitStack() as stack:
284
- for name, cfg in self.server_configs.items():
285
- if cfg.disabled:
286
- logger.info("MCP server %r is disabled; skipping.", name)
287
- continue
288
- try:
289
- # PER-SERVER bound, not just the caller's blanket
290
- # one. v2's list_tools() takes no
291
- # read_timeout_seconds, so a server that spawns and
292
- # then never answers the handshake would otherwise
293
- # consume the whole shared connect budget and starve
294
- # every server after it in this loop.
295
- async with asyncio.timeout(SERVER_CONNECT_TIMEOUT_S):
296
- client = await stack.enter_async_context(
297
- _TrackClose(
298
- Client(self._transport_for(cfg)), name,
299
- self._closed)
300
- )
301
- # Validation is by connection (§17 decision G):
302
- # a server that connects AND lists its tools is
303
- # usable. The listing IS registration's
304
- # catalogue (F8): cached below, served from,
305
- # never fetched a second time.
306
- tools = await client.list_tools()
307
- self.clients[name] = client
308
- self._catalogs[name] = list(tools.tools)
309
- logger.info("MCP server %r connected (%d tools).",
310
- name, len(tools.tools))
311
- except Exception as e:
312
- # One unreachable server must never take down the
313
- # others, or a single stale entry makes the whole
314
- # harness unusable. §17's sketch had no try/except
315
- # here at all.
316
- self.failures[name] = f"{type(e).__name__}: {e}"
317
- logger.warning("MCP server %r failed to connect: %s",
318
- name, e)
319
- self._ready.set()
320
- await self._shutdown.wait()
321
- except Exception:
322
- logger.exception("MCP manager task failed")
323
- if self._ready is not None and not self._ready.is_set():
324
- self._ready.set()
325
- finally:
326
- if self._done is not None:
327
- self._done.set()
328
-
329
- def connect_all(self, timeout: float = CONNECT_TIMEOUT_S) -> None:
330
- """Connect every configured server. Synchronous, callable from
331
- ordinary startup code; the bridge does the rest."""
332
- if not self.server_configs:
333
- return
334
- loop = _ensure_loop()
335
-
336
- async def _start():
337
- self._ready = asyncio.Event()
338
- self._shutdown = asyncio.Event()
339
- self._done = asyncio.Event()
340
- self._task = loop.create_task(self._manager())
341
- await self._ready.wait()
342
-
343
- try:
344
- asyncio.run_coroutine_threadsafe(_start(), loop).result(timeout=timeout)
345
- except Exception:
346
- # A timeout here used to abandon the manager permanently. It
347
- # would still be parked mid-connect holding every child process
348
- # already spawned, and NOTHING could close it: disconnect_all()
349
- # waits on _done, which a stuck manager never sets. So one hung
350
- # server orphaned every other server's subprocess -- the exact
351
- # inversion of this file's "one unreachable server must never
352
- # take down the others" invariant.
353
- self._cancel_manager()
354
- self.clients.clear()
355
- self._catalogs.clear()
356
- self._task = None
357
- _shutdown_loop()
358
- raise
359
-
360
- # -- calling ---------------------------------------------------------
361
-
362
- def list_tools(self, server_name: str, timeout: float = 30.0):
363
- """The server's tool catalogue. Serves the connect-time cache
364
- (F8) -- the one MCP call that had no protocol timeout -- and
365
- crosses the bridge only on a miss. A copy comes back, so a
366
- caller cannot mutate the cache."""
367
- cached = self._catalogs.get(server_name)
368
- if cached is not None:
369
- return list(cached)
370
- client = self.clients[server_name]
371
- fut = asyncio.run_coroutine_threadsafe(client.list_tools(), _ensure_loop())
372
- return fut.result(timeout=timeout).tools
373
-
374
- def call_tool(self, server_name: str, tool_name: str, params: dict,
375
- timeout: float = DEFAULT_CALL_TIMEOUT_S) -> dict:
376
- """The synchronous entry point every ToolSpec.handler calls.
377
-
378
- Looks ordinary to registry.dispatch() regardless of whether the
379
- caller sits on Textual's main loop, a worker thread, or a plain
380
- CLI script -- the bridge is what makes caller context irrelevant.
381
-
382
- Returns a plain dict, never a CallToolResult (D23, §17 AC6).
383
- """
384
- client = self.clients.get(server_name)
385
- if client is None:
386
- reason = self.failures.get(server_name, "not connected")
387
- return {"error": f"MCP server {server_name!r} is unavailable: {reason}"}
388
-
389
- loop = _ensure_loop()
390
- protocol_timeout = max(1.0, timeout - _TIMEOUT_MARGIN_S)
391
- coro = client.call_tool(tool_name, params,
392
- read_timeout_seconds=protocol_timeout)
393
- future = asyncio.run_coroutine_threadsafe(coro, loop)
394
- try:
395
- return _normalize(future.result(timeout=timeout))
396
- except MCPError as e:
397
- # v2 raises for protocol-level failures -- including timeout,
398
- # which is code -32001 -- where v1 reported everything in
399
- # band. Map onto the same {"error": ...} convention so the
400
- # loop keeps exactly one error shape to understand.
401
- return {"error": f"MCP call failed: {e}"}
402
- except TimeoutError:
403
- # The protocol timeout should have fired first. Reaching here
404
- # means the loop itself is wedged; cancel so the coroutine
405
- # can't outlive the call.
406
- future.cancel()
407
- return {"error": f"MCP tool {tool_name!r} timed out after {timeout}s"}
408
- except Exception as e:
409
- # LAST, so the two specific branches above keep their handling
410
- # (notably future.cancel()). MCPError is not the only thing v2
411
- # raises: an outputSchema violation surfaces as a bare
412
- # RuntimeError and a malformed payload as a pydantic
413
- # ValidationError. dispatch() has no handler-exception catch
414
- # and _run() catches only ToolCallDenied, so anything escaping
415
- # here takes down the whole conversation -- or all ten research
416
- # passes -- on one buggy third-party server. D23 promises this
417
- # function returns ONE error shape; that has to mean always.
418
- logger.debug("MCP call raised", exc_info=True)
419
- return {"error": f"MCP call failed: {type(e).__name__}: {e}"}
420
-
421
- # -- shutdown --------------------------------------------------------
422
-
423
- def _cancel_manager(self, timeout: float = SHUTDOWN_TIMEOUT_S) -> None:
424
- """Force the manager task to unwind its exit stack.
425
-
426
- Cancellation is the ONLY way to close the stack from outside the
427
- graceful path, and it works for the same reason the graceful path
428
- does: CancelledError is raised inside the manager's `async with`,
429
- so __aexit__ runs in the task that entered it. Calling aclose()
430
- from any other task is the cancel-scope error this module's
431
- docstring is about.
432
- """
433
- task, loop = self._task, _loop
434
- if task is None or loop is None:
435
- return
436
- try:
437
- async def _cancel():
438
- task.cancel()
439
- if self._done is not None:
440
- await self._done.wait()
441
- asyncio.run_coroutine_threadsafe(_cancel(), loop).result(timeout=timeout)
442
- except Exception as e:
443
- logger.warning("MCP manager task did not cancel cleanly: %s", e)
444
-
445
- def disconnect_all(self, timeout: float = None) -> None:
446
- """Close every session and stop the loop thread.
447
-
448
- Not tidiness: stdio servers are child processes THIS harness
449
- spawned. The daemon thread dies at interpreter exit without
450
- unwinding the stack, and the failure mode is orphaned
451
- subprocesses accumulating across sessions.
452
-
453
- F6 (#64): `timeout` is ONE budget for everything -- the polite
454
- close gets its first slice, force-cancel takes what remains
455
- (minus a join reserve), the loop-thread join takes the rest. It
456
- used to be three sequential SHUTDOWN_TIMEOUT_S waits, so one
457
- wedged server hung a quitting harness ~45s and Ctrl+C paid all
458
- of it. Servers that never confirmed a clean close by expiry are
459
- named in a WARNING.
460
- """
461
- budget = TEARDOWN_BUDGET_S if timeout is None else timeout
462
- if self._task is None or _loop is None:
463
- _shutdown_loop()
464
- return
465
-
466
- started = time.monotonic()
467
-
468
- def remaining() -> float:
469
- return max(0.0, budget - (time.monotonic() - started))
470
-
471
- graceful = False
472
- try:
473
- async def _stop():
474
- self._shutdown.set()
475
- await self._done.wait()
476
- asyncio.run_coroutine_threadsafe(_stop(), _loop).result(
477
- timeout=max(1.0, budget * 0.6))
478
- graceful = True
479
- except Exception as e:
480
- logger.warning("MCP shutdown did not complete cleanly within "
481
- "%.1fs of the %.1fs teardown budget: %s",
482
- max(1.0, budget * 0.6), budget, e)
483
- if not graceful:
484
- # The stack is still open and the children are still ours.
485
- # Asking politely didn't work, so cancel -- otherwise this
486
- # returns having reaped nothing while reporting only a warning.
487
- self._cancel_manager(timeout=max(1.0, remaining() - 1.0))
488
-
489
- stragglers = sorted(set(self.clients) - self._closed)
490
- if stragglers:
491
- logger.warning(
492
- "MCP server(s) %s did not confirm a clean close within the "
493
- "%.1fs teardown budget; their child processes may outlive "
494
- "this session.", ", ".join(stragglers), budget)
495
-
496
- self.clients.clear()
497
- self._catalogs.clear()
498
- self._task = None
499
- _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
+
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()))