credential_pool_plugin.py 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. """Plugin-provider refresh support for the credential pool (#116408).
  2. A model-provider plugin makes its pooled OAuth rows refreshable by shipping
  3. ``ProviderProfile.refresh_credential(entry) -> Mapping | None``. The pool owns
  4. the locking, persistence and failure classification around that hook; the
  5. plugin owns only the token POST. This sibling module keeps that logic out of
  6. ``agent/credential_pool.py`` (near the size cap).
  7. Contract (documented in website/docs/developer-guide/model-provider-plugin.md):
  8. * the hook returns a mapping of rotated values — dataclass field names
  9. (``access_token``, ``refresh_token``, ``expires_at_ms`` …) replace the row's
  10. fields, every other key (``expires_in``, ``token_type``, ``scope`` — the
  11. natural token-endpoint shape) lands in ``entry.extra``; ``None``/empty = could not
  12. rotate and the pool benches the row like a failed refresh POST;
  13. * raising ``AuthError(..., relogin_required=True)`` (or a grant-dead OAuth code)
  14. is terminal: the row goes DEAD with a WARNING naming ``hermes auth add``;
  15. any other exception is transient and only benches the row.
  16. """
  17. from __future__ import annotations
  18. import logging
  19. import time
  20. from dataclasses import fields, replace
  21. from typing import TYPE_CHECKING, Any, Mapping, Optional, Tuple
  22. from hermes_cli.auth import _OAUTH_GRANT_DEAD_CODES
  23. from hermes_cli.auth_constants import AuthError
  24. if TYPE_CHECKING: # pragma: no cover
  25. from agent.credential_pool import CredentialPool, PooledCredential
  26. logger = logging.getLogger(__name__)
  27. _EXPIRY_SKEW_MS = 120_000
  28. def plugin_row_is_expiring(entry: PooledCredential) -> bool:
  29. """An expiry-stamped OAuth row (a plugin's, or Anthropic's) is due within the skew of ``expires_at_ms``.
  30. The token endpoint's ``expires_in`` is the only clock: many providers issue opaque bearers (Google's
  31. ``ya29.*``) with no JWT ``exp`` to decode, so without this a long session sends the dead bearer.
  32. """
  33. return entry.expires_at_ms is not None and int(entry.expires_at_ms) <= int(time.time() * 1000) + _EXPIRY_SKEW_MS
  34. def apply_plugin_refresh_result(entry: PooledCredential, result: Any) -> PooledCredential:
  35. """Merge a ``refresh_credential`` return value into *entry*.
  36. Field names go through ``dataclasses.replace``; everything else is merged into ``extra``
  37. (mirroring ``PooledCredential.from_dict``). Before this split a token-endpoint-shaped mapping
  38. with ``expires_in`` raised ``TypeError`` inside ``replace`` and the pool benched a row whose
  39. single-use refresh token the server had already rotated — the login was lost.
  40. """
  41. if not result:
  42. return entry
  43. mapping: Mapping[str, Any] = dict(result)
  44. field_names = {f.name for f in fields(type(entry))} - {"provider", "extra"}
  45. field_updates = {k: v for k, v in mapping.items() if k in field_names}
  46. extra_updates = {k: v for k, v in mapping.items() if k not in field_names and k != "provider"}
  47. if extra_updates:
  48. field_updates["extra"] = {**entry.extra, **extra_updates}
  49. return replace(entry, **field_updates) if field_updates else entry
  50. def is_terminal_plugin_refresh_error(exc: BaseException) -> bool:
  51. """True when retrying the same plugin refresh token cannot succeed.
  52. Plugins have no per-provider code table, so the predicate is the structural one every built-in
  53. flow shares: a structured ``AuthError`` that asks for a re-login, or one carrying a grant-dead
  54. OAuth code. Transport errors, 429/5xx-shaped ``RuntimeError`` and plain ``AuthError`` without
  55. that signal stay transient (EXHAUSTED for one cooldown).
  56. """
  57. if not isinstance(exc, AuthError):
  58. return False
  59. return bool(exc.relogin_required) or (exc.code or "") in _OAUTH_GRANT_DEAD_CODES
  60. def recover_failed_plugin_refresh(
  61. pool: CredentialPool, entry: PooledCredential, exc: Exception,
  62. ) -> tuple[bool, Optional[PooledCredential]]:
  63. """Recovery for a plugin hook that raised: adopt a peer's rotation, or quarantine a dead grant.
  64. Returns ``(handled, result)``; ``handled=False`` means the caller should bench the row as a
  65. transient failure. A peer process may have rotated the single-use token between our in-lock
  66. sync and the hook's POST — adopt that pair before classifying the failure.
  67. """
  68. from agent.credential_pool import _MARK_OK
  69. synced = pool._sync_entry_from_pool_store(entry)
  70. if synced.refresh_token != entry.refresh_token and (synced.access_token or "").strip():
  71. logger.debug("%s refresh failed but the pool store has newer tokens — adopting", pool.provider)
  72. return True, pool._adopt(synced, **_MARK_OK)
  73. if is_terminal_plugin_refresh_error(exc):
  74. # WARNING, not debug: this is the moment a login is lost. Benching for a TTL would replay
  75. # the dead token every cooldown at DEBUG with no trace for the user.
  76. logger.warning(
  77. "%s refresh token for %s is terminally invalid (%s); the credential leaves rotation. "
  78. "Re-run 'hermes auth add %s' to sign in again.",
  79. pool.provider, entry.label or entry.id[:8], exc, pool.provider,
  80. )
  81. pool._mark_dead_refresh_grant(entry, exc)
  82. return True, None
  83. return False, None