managed_tool_gateway.py 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183
  1. """Generic managed-tool gateway helpers for Nous-hosted vendor passthroughs."""
  2. from __future__ import annotations
  3. import json
  4. import logging
  5. import os
  6. from dataclasses import dataclass
  7. from typing import Callable, Optional
  8. from hermes_constants import get_hermes_home
  9. from tools.tool_backend_helpers import managed_nous_tools_enabled
  10. logger = logging.getLogger(__name__)
  11. _DEFAULT_TOOL_GATEWAY_DOMAIN = "nousresearch.com"
  12. _DEFAULT_TOOL_GATEWAY_SCHEME = "https"
  13. _NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120
  14. @dataclass(frozen=True)
  15. class ManagedToolGatewayConfig:
  16. vendor: str
  17. gateway_origin: str
  18. nous_user_token: str
  19. managed_mode: bool
  20. def _clean(value: object) -> Optional[str]:
  21. """*value* stripped when it is a non-blank string, else None."""
  22. return value.strip() if isinstance(value, str) and value.strip() else None
  23. def auth_json_path():
  24. """Return the Hermes auth store path, respecting HERMES_HOME overrides."""
  25. return get_hermes_home() / "auth.json"
  26. def _read_nous_provider_state() -> Optional[dict]:
  27. """The profile's Nous state, or None. A free-tier identity counts only while guests are allowed:
  28. with ``nous.guest: false`` it is invisible here, so no cached or refreshed token of it is ever
  29. attached to a request.
  30. Resolves through the same profile-then-global-root fallback every other credential reader
  31. uses: a profile created with ``share_auth`` has no ``auth.json`` of its own and signs in with
  32. the root identity. Reading only ``HERMES_HOME/auth.json`` made that profile look signed out to
  33. the connector gate alone, so ``manage_connections`` vanished from its tool list."""
  34. try:
  35. from hermes_cli.auth import get_provider_auth_state
  36. nous_provider = get_provider_auth_state("nous")
  37. if not isinstance(nous_provider, dict):
  38. return None
  39. from hermes_cli.anon_auth import guest_allowed, is_guest_state
  40. if is_guest_state(nous_provider) and not guest_allowed():
  41. return None
  42. return nous_provider
  43. except Exception:
  44. return None
  45. def _read_user_token_override() -> Optional[str]:
  46. """Read the TOOL_GATEWAY_USER_TOKEN override through the secret scope. Scope verdict is authoritative
  47. when installed (a scoped miss must NOT borrow the process env under multiplex); ``os.environ`` only
  48. when unscoped. Any non-UnscopedSecretError failure propagates -- a failed scoped read must never
  49. silently borrow the ambient env."""
  50. from agent.secret_scope import UnscopedSecretError, get_secret
  51. try:
  52. explicit = get_secret("TOOL_GATEWAY_USER_TOKEN")
  53. except UnscopedSecretError:
  54. explicit = os.getenv("TOOL_GATEWAY_USER_TOKEN")
  55. return _clean(explicit)
  56. def peek_nous_access_token() -> Optional[str]:
  57. """Cheap token probe: env override or cached auth-store token, no expiry check and no network —
  58. availability scans must stay off the synchronous OAuth refresh path (:func:`read_nous_access_token`)."""
  59. from hermes_cli.anon_auth import held_connectors_token
  60. return _read_user_token_override() or _clean(held_connectors_token(_read_nous_provider_state()))
  61. def read_nous_access_token() -> Optional[str]:
  62. """Read a Nous Subscriber OAuth access token from auth store or env override.
  63. A read: with no Nous identity there is no bearer and the answer is None. The free-tier identity
  64. is created by the boot bootstrap or the first hosted connector action, never on a token-read
  65. path (NS-845 Q1.2). A retired free-tier credential IS replaced here, once: that is the explicit
  66. dead-credential rule, shared with inference.
  67. """
  68. if explicit := _read_user_token_override():
  69. return explicit
  70. nous_provider = _read_nous_provider_state() or {}
  71. if not nous_provider:
  72. return None
  73. from hermes_cli.anon_auth import held_connectors_token
  74. if fresh_token := _clean(held_connectors_token(nous_provider, skew_seconds=_NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS)):
  75. return fresh_token
  76. cached_token = peek_nous_access_token()
  77. try:
  78. from hermes_cli.auth import resolve_nous_access_token
  79. if refreshed_token := _clean(resolve_nous_access_token(refresh_skew_seconds=_NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS)):
  80. return refreshed_token
  81. except Exception as exc:
  82. # Same dead-credential rule as inference (one place decides it: anon_auth): a retired free-tier
  83. # identity is replaced once, here, instead of handing back its stale token forever.
  84. from hermes_cli.anon_auth import AnonCredentialDead
  85. if isinstance(exc, AnonCredentialDead):
  86. return _replace_dead_guest_token(nous_provider, str(exc.code or "anon_credential_dead"))
  87. logger.debug("Nous access token refresh failed: %s", exc)
  88. return cached_token
  89. def _replace_dead_guest_token(dead_state: dict, code: str = "anon_credential_dead") -> Optional[str]:
  90. from hermes_cli.anon_auth import ANON_ACCOUNT_LOCKED, clear_dead_guest, ensure_portal_identity
  91. from hermes_cli.auth import resolve_nous_access_token
  92. clear_dead_guest(code, dead_token=dead_state.get("anon_token"))
  93. # Same rule as inference: a locked account is retired but never silently replaced.
  94. if code == ANON_ACCOUNT_LOCKED:
  95. return None
  96. try:
  97. if ensure_portal_identity(explicit=True) is None:
  98. return None
  99. return _clean(resolve_nous_access_token(refresh_skew_seconds=_NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS))
  100. except Exception as exc:
  101. logger.debug("Nous free tier replacement after a retired credential failed: %s", exc)
  102. return None
  103. def get_tool_gateway_scheme() -> str:
  104. """Return configured shared gateway URL scheme."""
  105. scheme = os.getenv("TOOL_GATEWAY_SCHEME", "").strip().lower() or _DEFAULT_TOOL_GATEWAY_SCHEME
  106. if scheme not in {"http", "https"}:
  107. raise ValueError("TOOL_GATEWAY_SCHEME must be 'http' or 'https'")
  108. return scheme
  109. def build_vendor_gateway_url(vendor: str) -> str:
  110. """Return the gateway origin for a specific vendor."""
  111. if explicit_vendor_url := os.getenv(f"{vendor.upper().replace('-', '_')}_GATEWAY_URL", "").strip().rstrip("/"):
  112. return explicit_vendor_url
  113. shared_domain = os.getenv("TOOL_GATEWAY_DOMAIN", "").strip().strip("/") or _DEFAULT_TOOL_GATEWAY_DOMAIN
  114. return f"{get_tool_gateway_scheme()}://{vendor}-gateway.{shared_domain}"
  115. def _vendor_gateway(vendor: str, gateway_builder, token_reader) -> Optional[ManagedToolGatewayConfig]:
  116. gateway_origin = (gateway_builder or build_vendor_gateway_url)(vendor)
  117. nous_user_token = (token_reader or read_nous_access_token)()
  118. if not gateway_origin or not nous_user_token:
  119. return None
  120. return ManagedToolGatewayConfig(vendor=vendor, gateway_origin=gateway_origin, nous_user_token=nous_user_token, managed_mode=True)
  121. def resolve_managed_tool_gateway(
  122. vendor: str, gateway_builder: Optional[Callable[[str], str]] = None,
  123. token_reader: Optional[Callable[[], Optional[str]]] = None) -> Optional[ManagedToolGatewayConfig]:
  124. """Resolve shared managed-tool gateway config for a vendor (entitled accounts only)."""
  125. if not managed_nous_tools_enabled():
  126. return None
  127. return _vendor_gateway(vendor, gateway_builder, token_reader)
  128. def resolve_free_search_gateway(token_reader: Optional[Callable[[], Optional[str]]] = None) -> Optional[ManagedToolGatewayConfig]:
  129. """Perplexity ``search_type: "fast"`` is served to every Nous identity with no funding check, the
  130. anonymous guest tier included, so it needs a token this profile may use (guest-disabled and refresh
  131. rules live in the reader), not paid entitlement or a registered account. Search only: every other
  132. vendor route goes through :func:`resolve_managed_tool_gateway`."""
  133. return _vendor_gateway("perplexity", None, token_reader)
  134. def is_managed_tool_gateway_ready(
  135. vendor: str, gateway_builder: Optional[Callable[[str], str]] = None,
  136. token_reader: Optional[Callable[[], Optional[str]]] = None) -> bool:
  137. """True when a gateway URL and a likely-usable Nous token are present. Defaults to
  138. :func:`peek_nous_access_token` (no OAuth refresh); callers about to make a real request use
  139. :func:`resolve_managed_tool_gateway` instead."""
  140. return resolve_managed_tool_gateway(vendor, gateway_builder=gateway_builder, token_reader=token_reader or peek_nous_access_token) is not None