@yahyahammad/venastine 0.3.8 → 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 (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -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 +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -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 +2715 -2715
  28. package/core/commands.py +460 -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 +234 -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 +458 -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 +108 -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 +733 -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 +295 -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 +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,733 +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 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
+
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()))