"""Wire models for the gateway connector routes. Tolerate added gateway fields; callers receive plain dictionaries. Correlate results by position, never wire ``index``. """ from __future__ import annotations from typing import Any, Literal, Optional from pydantic import BaseModel, ConfigDict, Field CONNECTORS_PATH = "v1/connectors" CONNECTOR_SEARCH_PATH = f"{CONNECTORS_PATH}/search" CONNECTOR_SCHEMAS_PATH = f"{CONNECTORS_PATH}/schemas" CONNECTOR_EXECUTE_PATH = f"{CONNECTORS_PATH}/execute" CONNECTOR_CONNECTIONS_PATH = f"{CONNECTORS_PATH}/connections" CONNECTOR_ACCOUNTS_PATH = f"{CONNECTORS_PATH}/accounts" CONNECTOR_FILE_UPLOAD_PATH = f"{CONNECTORS_PATH}/files/upload" # The gateway's cap on a staged file's declared size. CONNECTOR_FILE_MAX_BYTES = 20 * 1024 * 1024 # The gateway's six-state account status (contract `CONNECTOR_CONNECTION_STATUSES`; the vendor's # INITIALIZING and INITIATED both arrive as `pending`). Present only once the session binds an # account; a value outside this set is a contract break and fails validation. ConnectionStatus = Literal["pending", "active", "failed", "expired", "revoked", "inactive"] # Where the vendor's done page sends the browser after consent; the dev desktop registers hermes-dev://. ConnectorReturnTarget = Literal["hermes-desktop", "hermes-desktop-dev", "portal"] # Who asked for a connect, so the gateway can attribute each minted link. The gateway sets # ``execute_link`` and ``portal`` itself; an older gateway ignores the field. ConnectorInitiator = Literal["agent_tool", "desktop_page", "card_retry"] # Hermes dispatch caps batches lower, so client-side chunking is deliberately absent. WIRE_BATCH_MAX = 25 # Any string: a gateway newer than this client may add codes, and an unknown code still renders. ConnectorErrorCode = str # `product`: the request or the user's setup is the cause. `backend`: the gateway or the vendor failed. ErrorFamily = Literal["product", "backend"] # Single-call execute failures: code -> (family, HTTP status). The legacy array envelope carries only # TOOL_NOT_ALLOWED, CONNECTION_REQUIRED, TOOL_NOT_FOUND and PROVIDER_ERROR, always under a 200. EXECUTE_ERROR_CODES: dict[str, tuple[ErrorFamily, int]] = { "TOOL_NOT_ALLOWED": ("product", 403), "CONNECTION_REQUIRED": ("product", 409), "CONNECTION_EXPIRED": ("product", 409), "ALIAS_REQUIRED": ("product", 422), "ALIAS_UNKNOWN": ("product", 422), "INVALID_ARGUMENTS": ("product", 422), "TOOL_NOT_FOUND": ("product", 404), "PROVIDER_ERROR": ("backend", 502), "PROVIDER_RATE_LIMITED": ("backend", 429), "PROVIDER_TIMEOUT": ("backend", 504), "POLICY_UNAVAILABLE": ("backend", 503), "GATEWAY_ERROR": ("backend", 500), } # Failures the agent reports itself while staging a file input, before the call reaches execute. FILE_ERROR_FAMILIES: dict[str, ErrorFamily] = { "FILE_NOT_ALLOWED": "product", "FILE_NOT_FOUND": "product", "FILE_TOO_LARGE": "product", "FILE_UPLOAD_FAILED": "backend", } def execute_error_family(code: str, family: Optional[str] = None) -> Optional[str]: """The gateway's family when it sent one, else the table's; ``None`` for an unknown code.""" if family in ("product", "backend"): return family known = EXECUTE_ERROR_CODES.get(code) return known[0] if known else FILE_ERROR_FAMILIES.get(code) class _Wire(BaseModel): model_config = ConfigDict(extra="ignore", populate_by_name=True) class ConnectorSearchQuery(_Wire): use_case: str = Field(alias="useCase") known_fields: Optional[str] = Field(default=None, alias="knownFields") class ConnectorSearchRequest(_Wire): queries: list[ConnectorSearchQuery] class ConnectorToolSchema(_Wire): connector: str tool: str description: str = "" input_schema: dict[str, Any] = Field(default_factory=dict, alias="inputSchema") class ConnectorSearchResult(_Wire): # Vendor passthrough; result correlation uses array position. index: int use_case: str = Field(default="", alias="useCase") tools: list[str] = Field(default_factory=list) related_tools: list[str] = Field(default_factory=list, alias="relatedTools") connectors: list[str] = Field(default_factory=list) guidance: Optional[str] = None plan_steps: Optional[list[str]] = Field(default=None, alias="planSteps") pitfalls: Optional[list[str]] = None error: Optional[str] = None class ConnectorConnectionStatus(_Wire): connector: str connected: bool = False description: str = "" class ConnectorSearchResponse(_Wire): results: list[ConnectorSearchResult] = Field(default_factory=list) schemas: dict[str, ConnectorToolSchema] = Field(default_factory=dict) connections: list[ConnectorConnectionStatus] = Field(default_factory=list) next_steps: list[str] = Field(default_factory=list, alias="nextSteps") class ConnectorSchemasRequest(_Wire): tools: list[str] class ConnectorSchemasResponse(_Wire): schemas: dict[str, ConnectorToolSchema] = Field(default_factory=dict) not_found: list[str] = Field(default_factory=list, alias="notFound") suggestions: dict[str, list[str]] = Field(default_factory=dict) class ConnectorFileUploadRequest(_Wire): toolkit: str tool: str filename: str mimetype: str size: int class ConnectorFileDescriptor(_Wire): """The value a ``file_uploadable`` tool input takes on the wire.""" name: str mimetype: str s3key: str class ConnectorFileUploadResponse(_Wire): upload_url: str = Field(alias="uploadUrl") headers: dict[str, str] = Field(default_factory=dict) descriptor: ConnectorFileDescriptor expires_at: str = Field(alias="expiresAt") class ConnectorToolError(_Wire): code: ConnectorErrorCode message: str connector: Optional[str] = None connect_url: Optional[str] = Field(default=None, alias="connectUrl") # The account the link was minted for; absent when the link mint failed. Absent means nothing to watch. connection_id: Optional[str] = Field(default=None, alias="connectionId") hint: Optional[str] = None family: Optional[str] = None class ConnectorExecuteFailure(ConnectorToolError): """The body of a non-2xx single-call execute answer.""" request_id: Optional[str] = Field(default=None, alias="requestId") class ConnectorExecuteCall(_Wire): connector: str tool: str arguments: dict[str, Any] = Field(default_factory=dict) # Never sent by hermes: the model picks an account with the ``connector_alias`` argument, which # the gateway strips and resolves itself. account: Optional[str] = None class ConnectorExecuteRequest(_Wire): tools: list[ConnectorExecuteCall] # Ride any CONNECTION_REQUIRED link the call mints back to the surface that asked. return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo") op: Optional[str] = Field(default=None, min_length=1, max_length=128) class ConnectorExecuteSingleRequest(_Wire): call: ConnectorExecuteCall return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo") op: Optional[str] = Field(default=None, min_length=1, max_length=128) # What a model receiving this result must guarantee; absent when the connector asks nothing. DataUseRequirement = Literal["no_training", "zero_retention"] class ConnectorDataUse(_Wire): requires: list[DataUseRequirement] class ConnectorExecuteSingleResult(_Wire): connector: str = "" tool: str = "" data: Any = None account: Optional[str] = None data_use: Optional[ConnectorDataUse] = Field(default=None, alias="dataUse") class ConnectorExecuteSingleResponse(_Wire): result: ConnectorExecuteSingleResult class ConnectorExecuteResult(_Wire): # Never correlate results by wire index. index: int = 0 connector: str = "" tool: str = "" data: Any = None error: Optional[ConnectorToolError] = None # The alias of the account the call ran under; null when that account has no alias. account: Optional[str] = None data_use: Optional[ConnectorDataUse] = Field(default=None, alias="dataUse") class ConnectorExecuteResponse(_Wire): results: list[ConnectorExecuteResult] = Field(default_factory=list) success_count: int = Field(default=0, alias="successCount") error_count: int = Field(default=0, alias="errorCount") total_count: int = Field(default=0, alias="totalCount") class ConnectorConnectionsRequest(_Wire): connectors: list[str] reinitiate: bool = False alias: Optional[str] = None # The existing account a reinitiate repairs; sent instead of ``alias`` when known. connection_id: Optional[str] = Field(default=None, alias="connectionId") return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo") # The caller's operation id, echoed on the hermes://connections/done link. op: Optional[str] = Field(default=None, min_length=1, max_length=128) initiator: Optional[ConnectorInitiator] = None class ConnectorConnectionResult(_Wire): connector: str status: Literal["active", "initiated", "failed"] connect_url: Optional[str] = Field(default=None, alias="connectUrl") # The vendor account the mint created or observed. Optional by vendor semantics (a no-auth toolkit # answers active with none); a target without one has nothing to watch. connection_id: Optional[str] = Field(default=None, alias="connectionId") alias: Optional[str] = None instruction: Optional[str] = None # Vendor error_message on ``failed``; the list route never carries it. status_reason: Optional[str] = Field(default=None, alias="statusReason") reinitiated: bool = False class ConnectorListItem(_Wire): connector: str enabled: bool = True connected: bool = False connection_status: Optional[ConnectionStatus] = Field(default=None, alias="connectionStatus") status_reason: Optional[str] = Field(default=None, alias="statusReason") gateway_disabled_tools: list[str] = Field(default_factory=list, alias="disabledTools") class ConnectorListResponse(_Wire): items: list[ConnectorListItem] next_cursor: Optional[str] = Field(default=None, alias="nextCursor") class ConnectorAccount(_Wire): connection_id: str = Field(alias="connectionId") connector: str status: ConnectionStatus status_reason: Optional[str] = Field(default=None, alias="statusReason") label: str = Field(min_length=1) alias: Optional[str] = None # The newest active account for this connector: the one the vendor executes with. active: bool # Retired by a reconnect that replaced it; kept, never selectable. disabled: bool = False created_at: str = Field(alias="createdAt") updated_at: str = Field(alias="updatedAt") class ConnectorAccountsResponse(_Wire): accounts: list[ConnectorAccount] class RemovedConnectorAccount(_Wire): connection_id: str = Field(alias="connectionId") connector: str status: Literal["removed"] class ConnectorConnectionsSummary(_Wire): total: int = 0 active: int = 0 initiated: int = 0 failed: int = 0 class ConnectorConnectionsResponse(_Wire): results: list[ConnectorConnectionResult] = Field(default_factory=list) summary: ConnectorConnectionsSummary = Field( default_factory=ConnectorConnectionsSummary )