| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135 |
- """Caller identity for requests to the first-party gateways: who is calling, and which turn asked.
- ``user_agent()`` goes on every request. The correlation headers name the conversation, turn and tool
- call, so they go only to connector routes and only when the profile has opted in to sending
- telemetry. The gateway strips every ``x-nous-`` header before it calls a vendor.
- """
- from __future__ import annotations
- import logging
- import uuid
- from dataclasses import dataclass
- from typing import Mapping, Optional
- logger = logging.getLogger(__name__)
- __all__ = [
- "CallRef",
- "connector_headers",
- "correlation_headers",
- "log_connector_outcome",
- "request_surface",
- "response_request_id",
- "user_agent",
- ]
- SESSION_HEADER = "x-nous-hermes-session"
- TURN_HEADER = "x-nous-hermes-turn"
- TOOL_CALL_HEADER = "x-nous-hermes-tool-call"
- REQUEST_ID_HEADER = "x-request-id"
- # sys.platform -> the shared-metrics OS family.
- _OS_FAMILY = {"darwin": "macos", "linux": "linux", "win32": "windows"}
- # The account route answers 404 with this code until the vendor has created the account.
- _EXPECTED_MISSES = frozenset({"connection_not_found"})
- @dataclass(frozen=True)
- class CallRef:
- """The model's ids for the call a request serves. Absent fields are not sent."""
- turn_id: Optional[str] = None
- tool_call_id: Optional[str] = None
- def _platform_name() -> str:
- """The session's platform: the running turn's agent platform, else the bound session vars.
- Off a turn (a desktop page action, an account operation thread) only the session vars exist.
- The classic CLI and one-shot runs bind neither, so they read as ``cli``."""
- from agent.relay_runtime import current_turn
- from gateway.session_context import get_session_env
- from tools.connectors.gateway.config import session_platform
- from utils import is_truthy_value
- turn = current_turn()
- if turn is not None and turn.lease.platform:
- return turn.lease.platform
- if platform := session_platform():
- return platform
- return "cron" if is_truthy_value(get_session_env("HERMES_CRON_SESSION", "")) else "cli"
- def request_surface() -> str:
- from hermes_cli.observability.shared_metrics_contract import execution_surface
- surface = execution_surface({"execution_surface": _platform_name()})
- return "other" if surface == "unknown" else surface
- def user_agent() -> str:
- from hermes_cli.version_info import get_version_info
- from hermes_platform.host.facts import os_family
- os_name = _OS_FAMILY.get(os_family(), "unknown")
- return f"hermes-agent/{get_version_info().base_version} ({request_surface()}; {os_name})"
- def _send_consented() -> bool:
- from hermes_cli.config import read_raw_config_readonly
- from hermes_cli.observability.shared_metrics_send_config import resolve_send_config
- return resolve_send_config(read_raw_config_readonly() or {}).send is True
- def _conversation_id() -> Optional[str]:
- from agent.portal_tags import get_conversation_context
- from gateway.session_context import get_session_env
- return get_conversation_context() or get_session_env("HERMES_SESSION_ID", "") or None
- def correlation_headers(call: Optional[CallRef] = None) -> dict[str, str]:
- """``x-request-id`` (fresh per HTTP attempt) and the conversation, turn and tool call ids, or
- ``{}`` when the profile has not opted in to sending telemetry."""
- if not _send_consented():
- return {}
- headers = {REQUEST_ID_HEADER: str(uuid.uuid4())}
- ids = {
- SESSION_HEADER: _conversation_id(),
- TURN_HEADER: call.turn_id if call else None,
- TOOL_CALL_HEADER: call.tool_call_id if call else None,
- }
- headers.update({name: str(value) for name, value in ids.items() if value})
- return headers
- def connector_headers(call: Optional[CallRef] = None) -> dict[str, str]:
- """Every identity header for one connector HTTP attempt. Call it once per attempt."""
- return {"User-Agent": user_agent(), **correlation_headers(call)}
- def response_request_id(response: object) -> Optional[str]:
- headers = getattr(response, "headers", None)
- if not isinstance(headers, Mapping):
- return None
- value = headers.get(REQUEST_ID_HEADER) or headers.get("X-Request-Id")
- return str(value) if value else None
- def log_connector_outcome(
- route: str, status: Optional[int], *, code: Optional[str] = None, request_id: Optional[str] = None,
- call: Optional[CallRef] = None,
- ) -> None:
- """One line per connector HTTP outcome: failures at WARNING, success and expected misses at DEBUG.
- The ``code`` makes a line a failure, not the status: a 200 whose body failed carries one, and a
- 304 that refreshed a cached list does not."""
- level = logging.WARNING if code is not None and code not in _EXPECTED_MISSES else logging.DEBUG
- logger.log(
- level, "connector %s %s %s request_id=%s dispatch=%s",
- route, status if status is not None else "transport", code or "-", request_id or "-",
- (call.tool_call_id if call else None) or "-",
- )
|