@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,15 @@
1
+ """
2
+ mcp_client/
3
+
4
+ MCP (Model Context Protocol) client -- ROADMAP_v2 §17.
5
+
6
+ NAMED `mcp_client`, NOT `mcp`, AND THAT IS LOAD-BEARING. The project root
7
+ is on sys.path, so a top-level `mcp/` package here would shadow the
8
+ installed MCP SDK and `import mcp` inside this very package would resolve
9
+ to itself. That is the `logging.py` incident (see AGENTS.md conventions)
10
+ with a worse blast radius. §17's spec sketches `mcp/client.py`; do not
11
+ follow it there.
12
+
13
+ Every symbol imported from the SDK lives inside this package, so a future
14
+ major-version migration touches one directory.
15
+ """
@@ -0,0 +1,499 @@
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()))