web_tools_rescue.py 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  1. """One-shot keyless-ring rescue for failed keyed/configured web calls.
  2. Stateless by design: a rescue routes THIS call through the free-tier ring (plugins/web/keyless_mcp.py);
  3. the next web_search/web_extract call attempts the chosen backend again. Callers must never cache a
  4. rescue-served response, or the one-shot rescue becomes sticky for a whole TTL. Logs under the origin
  5. (tools.web_tools) logger.
  6. """
  7. import logging
  8. logger = logging.getLogger("tools.web_tools")
  9. # Ring vendor -> env var holding its paid key (keyed mode ⇒ eligible for rescue).
  10. _RING_KEY_VARS = {
  11. "exa": "EXA_API_KEY", "parallel": "PARALLEL_API_KEY",
  12. "firecrawl": "FIRECRAWL_API_KEY", "keenable": "KEENABLE_API_KEY",
  13. }
  14. def _keyless_rescue_enabled() -> bool:
  15. """``web.keyless_rescue`` (default on), implicitly off when the keyless tier is disabled."""
  16. from tools.web_tools import _load_web_config
  17. if not _load_web_config().get("keyless_rescue", True):
  18. return False
  19. try:
  20. from agent.web_search_registry import _keyless_tier_enabled
  21. return _keyless_tier_enabled()
  22. except Exception as exc:
  23. logger.debug("keyless rescue tier check failed: %s", exc)
  24. return False
  25. def _ring_vendor_keyless(name: str) -> bool:
  26. """Did *name*'s own provider route this call through the anonymous keyless ring?
  27. Mirrors the predicate each ring provider evaluates before calling, so eligibility reflects what
  28. actually happened. Firecrawl owns extra routes that bypass the ring without a key — the managed
  29. Nous Tool Gateway (persisted ``nous`` selection, or the legacy never-configured fallback when the
  30. gateway is ready) and a self-hosted ``FIRECRAWL_API_URL`` — so it is asked directly.
  31. """
  32. if name == "firecrawl":
  33. from plugins.web.firecrawl.provider import _use_keyless_ring
  34. return _use_keyless_ring()
  35. from agent.web_search_provider import get_provider_env
  36. from plugins.web.keyless_mcp import use_keyless
  37. key_var = _RING_KEY_VARS.get(name, "")
  38. return use_keyless(name, get_provider_env(key_var) if key_var else "")
  39. def _managed_search_fallback(provider, original_error: str, query: str, limit: int):
  40. """Try managed Firecrawl for this call only; None leaves the original error for keyless rescue.
  41. Managed Firecrawl is billed, so a caller on free fast search alone never reaches it."""
  42. from agent.web_search_provider import get_provider_env
  43. from tools import web_tools as _wt
  44. if (getattr(provider, "name", "") != "perplexity"
  45. or get_provider_env("PERPLEXITY_API_KEY") or not _wt._managed_web_search() or not _wt._is_tool_gateway_ready()):
  46. return None
  47. logger.warning("web_search managed Perplexity failed (%s); serving this call from managed Firecrawl", (original_error or "")[:200])
  48. try:
  49. from agent.web_search_registry import get_provider
  50. resp = get_provider("firecrawl").search(query, limit)
  51. except Exception as exc:
  52. resp = {"success": False, "error": str(exc)}
  53. if not resp.get("success"):
  54. logger.warning("managed Firecrawl fallback failed too: %s", str(resp.get("error", ""))[:200])
  55. return None
  56. resp.setdefault("data", {}).update(
  57. fallback_from="managed_primary",
  58. backend_error=f"Primary managed search failed this call ({(original_error or 'unknown error')[:300]}); "
  59. "result served by the managed fallback. The next call will use the primary again.",
  60. )
  61. return resp
  62. def _rescue_eligible(provider) -> bool:
  63. """True when a failed call on *provider* should get a one-shot rescue.
  64. Eligible: any call that did NOT go through the keyless ring — a non-ring backend, a ring vendor
  65. in keyed mode, or a ring vendor routed through the managed gateway / a self-hosted instance. A
  66. ring vendor that walked the ring is NOT eligible: its failure means the ring already failed.
  67. """
  68. if not _keyless_rescue_enabled() or provider is None:
  69. return False
  70. try:
  71. from plugins.web.keyless_mcp import _KEYLESS_RING
  72. name = getattr(provider, "name", "")
  73. return name not in _KEYLESS_RING or not _ring_vendor_keyless(name)
  74. except Exception as exc:
  75. logger.debug("rescue eligibility check failed: %s", exc)
  76. return False
  77. def _rescue_search(provider_name: str, original_error: str, query: str, limit: int) -> dict:
  78. """Rescue a failed search via the ring; annotate the result with the original failure."""
  79. from plugins.web.keyless_mcp import search_with_failover
  80. logger.warning(
  81. "web_search backend '%s' failed (%s); one-shot keyless rescue",
  82. provider_name, (original_error or "")[:200],
  83. )
  84. rescued = search_with_failover(provider_name, query, limit)
  85. if rescued.get("success"):
  86. rescued.setdefault("data", {}).update(
  87. rescued_from=provider_name,
  88. backend_error=(
  89. f"Configured backend '{provider_name}' failed this call "
  90. f"({(original_error or 'unknown error')[:300]}); result served by the keyless free tier. "
  91. f"The next call will use '{provider_name}' again."
  92. ),
  93. )
  94. return rescued
  95. # Ring also failed: the ORIGINAL error names the user's setup, so lead with it.
  96. return {
  97. "success": False,
  98. "error": (
  99. f"{original_error or 'search failed'} "
  100. f"(keyless rescue also failed: {rescued.get('error', 'unknown')})"
  101. ),
  102. }
  103. def _policy_blocked_result(result: dict) -> bool:
  104. """True for a website-policy refusal — intentional, never rescued (it would fetch blocked content)."""
  105. error = str(result.get("error") or "").lower()
  106. return bool(result.get("blocked_by_policy")) or "blocked by website policy" in error
  107. def _rescue_extract(provider_name: str, urls: list, results: list) -> list:
  108. """Rescue a whole-batch extract failure via the ring.
  109. Only genuine failures are re-fetched; policy-blocked entries are preserved verbatim. If the provider
  110. broke url/result order parity, every entry is treated as rescueable and the ring's list replaces the
  111. batch wholesale.
  112. """
  113. from plugins.web.keyless_mcp import extract_with_failover
  114. parity = len(results) == len(urls)
  115. rescue_idx = [i for i, r in enumerate(results) if not parity or not _policy_blocked_result(r)]
  116. if not rescue_idx:
  117. return results # every failure is an intentional policy block
  118. rescue_urls = [urls[i] for i in rescue_idx] if parity else list(urls)
  119. errors = (results[i].get("error") for i in rescue_idx if results[i].get("error"))
  120. original_error = next(errors, "extract failed")
  121. logger.warning(
  122. "web_extract backend '%s' failed all %d URL(s) (%s); one-shot keyless rescue",
  123. provider_name, len(rescue_urls), (original_error or "")[:200],
  124. )
  125. rescued = extract_with_failover(provider_name, list(rescue_urls))
  126. if rescued and all(r.get("error", "") for r in rescued):
  127. return results # rescue also failed everywhere: keep original errors
  128. for r in rescued:
  129. meta = None if r.get("error") else r.setdefault("metadata", {})
  130. if isinstance(meta, dict):
  131. meta["rescued_from"] = provider_name
  132. meta["backend_error"] = (original_error or "")[:300]
  133. if parity and len(rescued) == len(rescue_idx):
  134. replacements = dict(zip(rescue_idx, rescued))
  135. return [replacements.get(i, r) for i, r in enumerate(results)]
  136. return rescued