| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177 |
- """Gateway HTTP errors and envelope parsing.
- Per-tool execute failures are result entries, not exceptions; connection links are intentionally unredacted for the model to relay.
- """
- from __future__ import annotations
- from typing import Any, Mapping, Optional
- from tools.connectors.turn import CARD, LINK, SIDE
- __all__ = [
- "SIDE_AGENT_HINT",
- "GatewayAuthError",
- "GatewayUnavailable",
- "IdempotencyConflict",
- "ToolGatewayError",
- "parse_gateway_error",
- "render_connection_required",
- ]
- class ToolGatewayError(RuntimeError):
- """HTTP-level gateway failure; ``retryable`` is decided by the envelope parser."""
- def __init__(
- self,
- message: str,
- *,
- code: str = "GATEWAY_ERROR",
- status: Optional[int] = None,
- request_id: Optional[str] = None,
- retryable: bool = False,
- ) -> None:
- super().__init__(message)
- self.code = code
- self.status = status
- self.request_id = request_id
- self.retryable = retryable
- class GatewayAuthError(ToolGatewayError):
- """Authentication or entitlement failure."""
- class GatewayUnavailable(ToolGatewayError):
- """404 signals callers to degrade silently to local-only behavior."""
- class IdempotencyConflict(ToolGatewayError):
- """Never retry a reused idempotency key with a different body."""
- class RateLimited(ToolGatewayError):
- """429 with the gateway's retry hint in seconds; the caller decides whether to wait."""
- def __init__(self, message: str, *, retry_after: float, **kwargs: Any) -> None:
- super().__init__(message, **kwargs)
- self.retry_after = retry_after
- def parse_gateway_error(status: int, body: Any, headers: Optional[Mapping[str, Any]] = None) -> ToolGatewayError:
- """Parse every gateway error envelope without raising on a malformed body.
- Three envelope shapes exist: ``{error: {code, message}}`` on most routes, ``{error: "<code>"}``
- on the account routes, and a flat ``{code, message, requestId, retryAfterMs}`` on a 429."""
- code = f"HTTP_{status}"
- message = ""
- request_id = None
- retry_after_ms: Optional[float] = None
- if isinstance(body, Mapping):
- envelope = body.get("error")
- if isinstance(envelope, Mapping):
- code = str(envelope.get("code") or code)
- message = str(envelope.get("message") or "")
- elif isinstance(envelope, str) and envelope:
- code = envelope
- elif body.get("code"):
- code = str(body["code"])
- message = str(body.get("message") or "")
- raw_request_id = body.get("requestId")
- if raw_request_id is not None:
- request_id = str(raw_request_id)
- if isinstance(body.get("retryAfterMs"), (int, float)):
- retry_after_ms = float(body["retryAfterMs"])
- elif body:
- message = str(body)[:500]
- if not message:
- message = f"tool gateway request failed with status {status}"
- kwargs = {
- "code": code,
- "status": status,
- "request_id": request_id,
- }
- if status in (401, 403):
- return GatewayAuthError(message, **kwargs)
- if status == 404:
- return GatewayUnavailable(message, **kwargs)
- if status == 409:
- return IdempotencyConflict(message, **kwargs)
- if status == 429:
- header = (headers or {}).get("Retry-After") if headers else None
- retry_after = float(header) if header not in (None, "") else (retry_after_ms or 1000.0) / 1000.0
- return RateLimited(message, retry_after=retry_after, **kwargs)
- return ToolGatewayError(message, retryable=status >= 500, **kwargs)
- SIDE_AGENT_HINT = (
- "This app is not connected. Only the main agent can connect it, so report that back "
- "instead of trying to connect it here."
- )
- CARD_HINT = (
- "This app is not connected. Call manage_connections to open a connection card for it; "
- "there is no link to show the user."
- )
- # CONNECTION_EXPIRED: the account exists but the vendor no longer accepts it.
- EXPIRED_SIDE_AGENT_HINT = (
- "This app's connection expired. Only the main agent can reconnect it, so report that back "
- "instead of trying to reconnect it here."
- )
- EXPIRED_CARD_HINT = (
- "This app's connection expired. Call manage_connections with action 'reconnect' to open a "
- "connection card for it; there is no link to show the user."
- )
- EXPIRED_LINK_HINT = "The connection expired. Show the user the connect_url to reconnect, then retry the call."
- _HINTS = {
- "CONNECTION_REQUIRED": {SIDE: SIDE_AGENT_HINT, CARD: CARD_HINT},
- "CONNECTION_EXPIRED": {SIDE: EXPIRED_SIDE_AGENT_HINT, CARD: EXPIRED_CARD_HINT, LINK: EXPIRED_LINK_HINT},
- }
- def render_connection_required(
- *,
- connector: Optional[str] = None,
- message: Optional[str] = None,
- connect_url: Optional[str] = None,
- hint: Optional[str] = None,
- surface: str = LINK,
- code: str = "CONNECTION_REQUIRED",
- ) -> dict[str, Any]:
- """The model-facing shape for an app the call cannot use until the user connects it.
- ``code`` is CONNECTION_REQUIRED or CONNECTION_EXPIRED; both keep the card and link behaviour,
- the expired one with reconnect wording."""
- hints = _HINTS.get(code, _HINTS["CONNECTION_REQUIRED"])
- payload: dict[str, Any] = {
- "code": code,
- "message": message or _default_message(code, connector),
- }
- if connector:
- payload["connector"] = connector
- if surface == SIDE:
- payload["hint"] = hints[SIDE]
- return payload
- if surface == CARD:
- payload["connect_card_available"] = True
- payload["hint"] = hints[CARD]
- return payload
- if connect_url:
- payload["connect_url"] = connect_url
- hint = hint or hints.get(LINK)
- if hint:
- payload["hint"] = hint
- return payload
- def _default_message(code: str, connector: Optional[str]) -> str:
- app = f"The {connector} connector" if connector else "This connector"
- if code == "CONNECTION_EXPIRED":
- return f"{app} connection for this account has expired and must be reconnected."
- return f"{app} is not connected for this account."
|