provider.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
  1. """DuckDuckGo search via the optional ``ddgs`` package (search only, no key). ``is_available()``
  2. reflects package importability; the plugin registers either way so ``hermes tools`` can offer to
  3. install it. Isolation: ``ddgs``/``primp`` can block inside native code while holding the GIL, so a
  4. thread-pool ``future.result(timeout=…)`` cap can never fire and Ctrl+C/SIGTERM freeze the process —
  5. each search runs in a disposable child process the parent can terminate/kill.
  6. """
  7. from __future__ import annotations
  8. import concurrent.futures as cf
  9. import json
  10. import logging
  11. import os
  12. import subprocess
  13. import sys
  14. import time
  15. from typing import Any, Dict, Optional
  16. from plugins.web._common import BaseWebSearchProvider, search_fail, search_ok, setup_schema, title_hit
  17. logger = logging.getLogger(__name__)
  18. # Hard wall-clock cap per search: ``DDGS(timeout=…)`` only bounds individual HTTP requests;
  19. # ddgs's multi-engine retry loop has no overall cap, so a rate-limited response could
  20. # otherwise hang the shared agent loop indefinitely.
  21. # Enforce a hard cap here by killing a disposable worker process (#68096).
  22. _SEARCH_TIMEOUT_SECS = 30
  23. _POLL_INTERVAL_SECS = 0.1 # parent stdout / interrupt-flag poll cadence
  24. _TERMINATE_GRACE_SECS = 1.0 # wait after terminate() before escalating to kill()
  25. _test_hook: Optional[str] = None # test-only hook forwarded to the child (see _search_worker.py)
  26. _last_worker_proc: Optional[subprocess.Popen] = None # last worker Popen (test reap checks)
  27. class _SearchInterrupted(Exception):
  28. """Raised when tools.interrupt.is_interrupted() trips during a search wait."""
  29. def _run_ddgs_search(query: str, safe_limit: int) -> list[dict[str, Any]]:
  30. """Blocking ddgs query → normalized hits (module-level: the child worker imports it,
  31. tests patch it for in-process runs).
  32. ``DDGS(timeout=…)`` bounds each individual HTTP request; the overall wall-clock cap is enforced by the
  33. parent via process timeout (#68096).
  34. """
  35. from ddgs import DDGS # type: ignore
  36. results: list[dict[str, Any]] = []
  37. with DDGS(timeout=10) as client:
  38. for i, hit in enumerate(client.text(query, max_results=safe_limit)):
  39. if i >= safe_limit:
  40. break
  41. results.append(title_hit(str(hit.get("title", "")), str(hit.get("href") or hit.get("url") or ""), str(hit.get("body", "")), i + 1))
  42. return results
  43. def _plugins_path_entry() -> str:
  44. """``sys.path`` entry that makes ``import plugins`` work in the child (live package
  45. location first; correct for source checkouts and site-packages)."""
  46. try:
  47. import plugins as plugins_pkg
  48. if pkg_file := getattr(plugins_pkg, "__file__", None):
  49. return os.path.dirname(os.path.dirname(os.path.abspath(pkg_file)))
  50. except Exception:
  51. pass
  52. return os.path.abspath(os.path.join(__file__, *([os.pardir] * 4)))
  53. def _terminate_and_reap(proc: Optional[subprocess.Popen], *, grace: float = _TERMINATE_GRACE_SECS) -> None:
  54. """Terminate a worker, escalate to kill, and wait so no orphan remains. Does not close
  55. the parent's pipe ends — closing stdout while another thread is blocked in ``read()``
  56. deadlocks on some platforms; the caller drains first."""
  57. if proc is None:
  58. return
  59. alive = False
  60. def _wait_until_dead() -> bool:
  61. deadline = time.monotonic() + grace
  62. while proc.poll() is None and time.monotonic() < deadline:
  63. time.sleep(0.05)
  64. return proc.poll() is not None
  65. try:
  66. for escalate in (proc.terminate, proc.kill):
  67. if proc.poll() is None:
  68. escalate()
  69. alive = not _wait_until_dead()
  70. if alive:
  71. logger.warning("DDGS worker pid=%s did not exit after kill", proc.pid)
  72. except Exception as exc:
  73. logger.debug("DDGS worker reap error: %s", exc)
  74. def _spawn_worker(env: dict[str, str]) -> subprocess.Popen:
  75. """Start ``_search_worker.py`` as a script with ``plugins`` importable. Running as a
  76. script puts ``plugins/web/ddgs/`` on ``sys.path[0]``, breaking ``import plugins...``,
  77. so the real package location is prepended to PYTHONPATH."""
  78. # pm store PATH: the worker runs under the STORE python, whose third-party
  79. # imports (ddgs/primp) arrive via the launcher-composed PYTHONPATH. The
  80. # sanitizer strips Hermes-owned entries (cross-version protection); this
  81. # worker is the SAME interpreter, so merge the ambient PYTHONPATH back in.
  82. _ambient_pp = os.environ.get("PYTHONPATH")
  83. if _ambient_pp:
  84. _current = env.get("PYTHONPATH", "")
  85. env["PYTHONPATH"] = (
  86. _ambient_pp + os.pathsep + _current if _current else _ambient_pp
  87. )
  88. child_pythonpath = env.get("PYTHONPATH", "")
  89. path_entry = _plugins_path_entry()
  90. if path_entry and path_entry not in child_pythonpath.split(os.pathsep):
  91. env["PYTHONPATH"] = path_entry + os.pathsep + child_pythonpath if child_pythonpath else path_entry
  92. worker_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_search_worker.py")
  93. # Own process group/session. The 30 s cap terminates then kills the worker's pid only, not its group.
  94. # detached-spawn: ok — awaited under a 30 s cap that kills the worker; an owner killed mid-search leaves it running until that search returns (unbounded if primp hangs)
  95. extra_kwargs: dict[str, Any] = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if sys.platform == "win32" else {"start_new_session": True}
  96. # stdin/stdout/stderr stay explicit keyword args so scripts/check_subprocess_stdin.py sees them
  97. # (TUI gateway inherits stdin). stderr=DEVNULL: a chatty child would deadlock a stdout-only drain.
  98. return subprocess.Popen(
  99. [sys.executable, worker_path], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
  100. env=env, text=True, encoding="utf-8", errors="replace", **extra_kwargs,
  101. )
  102. def _parse_envelope(raw: str, proc: subprocess.Popen) -> list[dict[str, Any]]:
  103. """Decode the worker's stdout envelope; raise ``RuntimeError`` on any malformed shape."""
  104. raw = raw.strip()
  105. if not raw:
  106. raise RuntimeError(f"DDGS worker exited without a result (code={proc.poll()})")
  107. try:
  108. envelope = json.loads(raw)
  109. except json.JSONDecodeError as exc:
  110. raise RuntimeError(f"DDGS worker returned invalid JSON: {raw[:200]!r}") from exc
  111. if not isinstance(envelope, dict):
  112. raise RuntimeError(f"DDGS worker returned an invalid envelope: {envelope!r}")
  113. if not envelope.get("ok"):
  114. raise RuntimeError(str(envelope.get("error") or "DDGS worker failed"))
  115. results = envelope.get("results") or []
  116. if not isinstance(results, list):
  117. raise RuntimeError("DDGS worker returned non-list results")
  118. return results
  119. def _run_ddgs_search_bounded(query: str, safe_limit: int) -> list[dict[str, Any]]:
  120. """Run ``_run_ddgs_search`` in a disposable process with a hard deadline. The parent
  121. never joins a child that may be in native code holding *its* GIL — it polls a
  122. communicator thread and, on timeout/interrupt, kills the OS process.
  123. Raises ``TimeoutError``, ``_SearchInterrupted``, or ``RuntimeError``."""
  124. from tools.interrupt import is_interrupted # lazy: keep plugin import light
  125. from tools.environments.local import _sanitize_subprocess_env
  126. global _last_worker_proc
  127. request: dict[str, Any] = {"query": query, "safe_limit": safe_limit}
  128. env = _sanitize_subprocess_env(dict(os.environ))
  129. if _test_hook:
  130. request["test_hook"] = _test_hook
  131. env["HERMES_DDGS_ALLOW_TEST_HOOKS"] = "1"
  132. proc = _last_worker_proc = _spawn_worker(env)
  133. # ``communicate`` runs in a side thread so the parent can poll interrupt /
  134. # deadline without blocking; killing the child unblocks it.
  135. pool = cf.ThreadPoolExecutor(max_workers=1)
  136. fut = pool.submit(proc.communicate, json.dumps(request))
  137. interrupted, done, raw = False, False, ""
  138. try:
  139. deadline = time.monotonic() + _SEARCH_TIMEOUT_SECS
  140. while not done and not (interrupted := is_interrupted()) and (remaining := deadline - time.monotonic()) > 0:
  141. try:
  142. raw, done = fut.result(timeout=min(_POLL_INTERVAL_SECS, remaining))[0] or "", True
  143. except cf.TimeoutError:
  144. pass
  145. finally:
  146. _terminate_and_reap(proc)
  147. # After kill, communicate should return promptly; don't block forever.
  148. if not fut.done():
  149. try:
  150. raw = raw or fut.result(timeout=_TERMINATE_GRACE_SECS)[0] or ""
  151. except Exception:
  152. pass
  153. pool.shutdown(wait=False, cancel_futures=True)
  154. if interrupted:
  155. raise _SearchInterrupted("DuckDuckGo search interrupted")
  156. if not done:
  157. raise TimeoutError(f"DuckDuckGo search timed out after {_SEARCH_TIMEOUT_SECS}s")
  158. return _parse_envelope(raw, proc)
  159. class DDGSWebSearchProvider(BaseWebSearchProvider):
  160. """DuckDuckGo HTML-scrape search provider (no API key; DDG rate-limits server-side).
  161. ddgs errors surface as ``{"success": False, "error": ...}`` rather than raising."""
  162. NAME = "ddgs"
  163. DISPLAY_NAME = "DuckDuckGo (ddgs)"
  164. def is_available(self) -> bool:
  165. """True when ``ddgs`` is importable. Must NOT do network I/O — runs at
  166. tool-registration time and on every ``hermes tools`` paint."""
  167. try:
  168. import ddgs
  169. return True
  170. except ImportError:
  171. return False
  172. def search(self, query: str, limit: int = 5) -> dict[str, Any]:
  173. """Run the search in a disposable child with a hard wall-clock timeout so a
  174. hung native ``primp`` call cannot freeze the Hermes process.
  175. See #36776, #68096.
  176. """
  177. if not self.is_available():
  178. return search_fail("ddgs package is not installed — run `pip install ddgs`")
  179. try:
  180. # max(1, …): defensive cap in case the package ignores its max_results hint.
  181. web_results = _run_ddgs_search_bounded(query, max(1, int(limit)))
  182. except TimeoutError:
  183. logger.warning("DDGS search timed out after %ds for query: %r", _SEARCH_TIMEOUT_SECS, query)
  184. return search_fail(
  185. f"DuckDuckGo search timed out after {_SEARCH_TIMEOUT_SECS}s — "
  186. "DuckDuckGo may be rate-limiting or slow. Try again later or switch to a different search provider."
  187. )
  188. except _SearchInterrupted:
  189. logger.info("DDGS search interrupted for query: %r", query)
  190. return search_fail("DuckDuckGo search interrupted")
  191. except Exception as exc:
  192. logger.warning("DDGS search error: %s", exc)
  193. return search_fail(f"DuckDuckGo search failed: {exc}")
  194. logger.info("DDGS search '%s': %d results (limit %d)", query, len(web_results), limit)
  195. return search_ok(web_results)
  196. def get_setup_schema(self) -> dict[str, Any]:
  197. # post_setup triggers `_run_post_setup("ddgs")` so the package gets pip-installed on first pick.
  198. return setup_schema(
  199. "DuckDuckGo (ddgs)", "free · no key · search only",
  200. "Search via the ddgs Python package — no API key (pair with any extract provider)", post_setup="ddgs",
  201. )