"""The ``manage_connections`` card on the session authority: ``connection.respond``, the operation's ``status``/``wake`` and the card's Try again (``connectors.connect`` with ``reconnect``), plus the open card a resume restores (``pending_connection``). The operation lives in ``tools/connectors/live.py`` under the turn's session key (the live session's route) and profile, so a card can only drive its own session's operation. Account-owned calls (the Connectors page) are not the session's and stay on the legacy handlers (``tui_gateway/methods_connectors.py``). Answers and refusals share that file's code (``tools.connectors.run.respond``, ``tui_gateway/connector_refusals.py``); ``ConnectorRefusal`` carries a refusal through the authority's error path. """ import asyncio from functools import partial from hermes_state_runtime import RuntimeStoreError METHODS = ('connection.respond', 'connectors.operation.status', 'connectors.operation.wake', 'connectors.connect') class ConnectorRefusal(RuntimeStoreError): """A refusal on the legacy connector handlers' wire shape: their code, their human message, their ``ConnectorErrorReason`` as ``data.reason``.""" def __init__(self, code, reason, message): super().__init__(str(reason), detail=message) self.wire_code, self.wire_message = code, message def session_owned(params) -> bool: owner = params.get('owner') if isinstance(params, dict) else None return isinstance(owner, dict) and owner.get('type') == 'session' def handlers(connection): return {method: partial(_handle, connection, method) for method in METHODS} def pending_connection(authority, session_id): """The open operation of a live session as its ``connection.request`` payload, or None.""" from tools.connectors import live operation = live.current(authority.sessions[session_id].route, profile_home=authority.profile_id) return operation.request_payload() if operation is not None else None def _request(method, params): """The validated envelope and, for ``connection.respond``, the answer validated on its own as the legacy handler does: a bad answer is ``INVALID_ANSWER``, not a bad envelope.""" from pydantic import ValidationError from tui_gateway.connector_refusals import INVALID_ANSWER, INVALID_PARAMS from tui_gateway.contracts.connectors_operation import ConnectionAnswer, ConnectionOperationParams from tui_gateway.contracts.registry import METHODS as CONTRACTS respond = method == 'connection.respond' contract = ConnectionOperationParams if respond else CONTRACTS[method].params try: request = contract.model_validate({k: v for k, v in params.items() if not (respond and k == 'result')}) except ValidationError as exc: raise ConnectorRefusal(*INVALID_PARAMS) from exc if not respond: return request, None try: return request, ConnectionAnswer.model_validate(params.get('result')) except ValidationError as exc: raise ConnectorRefusal(*INVALID_ANSWER) from exc def _view(operation): from tui_gateway.connector_payload import connector_ui_payload snapshot = operation.snapshot() return connector_ui_payload({**snapshot, 'settled': snapshot.get('settled_at') is not None}) async def _handle(connection, method, _ref, params): from gateway.session_busy_controls import authorize from gateway.session_contract import SessionRef from tools.connectors import live from tui_gateway import connector_refusals as refusals request, answer = _request(method, params) authority = connection.authority ref = SessionRef(authority.profile_id, request.owner.session_id) # Capability before existence, as every authority verb: a refused caller learns nothing about the id. authorize(connection, ref, params, 'session:read' if method == 'connectors.operation.status' else 'session:control') if ref.session_id not in authority.sessions: raise RuntimeStoreError('not_found') route = authority.sessions[ref.session_id].route if method == 'connectors.connect': operation = live.current(route, profile_home=authority.profile_id) else: operation = live.get(route, request.op_id, profile_home=authority.profile_id) if operation is None: raise ConnectorRefusal(*refusals.UNKNOWN_OPERATION) if method == 'connectors.operation.status': return _view(operation) if method == 'connectors.operation.wake': operation.wake.set() return {'status': 'ok'} if method == 'connection.respond': return await asyncio.to_thread(_respond, operation, answer) return await asyncio.to_thread(_retry, authority, ref, operation, request) def _respond(operation, answer): from tools.connectors.operation import IllegalTransition from tools.connectors.run import respond from tui_gateway.connector_refusals import INVALID_ANSWER try: return {'status': 'ok', 'settled': respond(operation, answer.model_dump_json(exclude_none=True))} except IllegalTransition as exc: raise ConnectorRefusal(*INVALID_ANSWER) from exc def _retry(authority, ref, operation, request): """The card's Try again, under the session's own context, as the sidecar ran it for its session.""" from tools.connectors import run from tools.connectors.gateway.errors import GatewayAuthError from tui_gateway.connector_refusals import (INVALID_PARAMS, REISSUE_REFUSALS, REISSUE_REFUSED, REQUEST_FAILED, UNKNOWN_TARGET_REFUSAL, auth_refusal) if not request.reconnect: raise ConnectorRefusal(*INVALID_PARAMS) for name in request.connectors: target = operation.target(name) # A retry naming another account must not re-mint this one. if target is not None and ((request.alias is not None and target.alias != request.alias) or request.connection_id not in (None, target.repair_id, target.connection_id)): raise ConnectorRefusal(*UNKNOWN_TARGET_REFUSAL) with _session_context(authority, ref): _require_connectors(authority, ref) try: reason = run.reissue(operation, request.connectors) except RuntimeStoreError: raise except GatewayAuthError as exc: raise ConnectorRefusal(*auth_refusal(exc)) from exc except Exception as exc: # health: allow BLE001 -- the sidecar's _connector_guard: one named failure raise ConnectorRefusal(*REQUEST_FAILED) from exc if reason is not None: raise ConnectorRefusal(*REISSUE_REFUSALS.get(reason, REISSUE_REFUSED)) return _view(operation) def _require_connectors(authority, ref): """The sidecar's ``_session_connector_gate``: connectors on, and ``manage_connections`` in the session's tools.""" import model_tools from tools.connectors import connectors_available from tui_gateway import connector_refusals as refusals enabled, disabled = _session_toolsets(authority, ref) if 'manage_connections' not in model_tools._select_tool_names(enabled, disabled, quiet_mode=True) or not connectors_available(): raise ConnectorRefusal(*refusals.CONNECTORS_UNAVAILABLE) def _session_toolsets(authority, ref): agent = authority.agent(ref) if agent is not None: return getattr(agent, 'enabled_toolsets', None), getattr(agent, 'disabled_toolsets', None) from agent.skill_utils import parse_config_string_list from gateway.session_policy import policy_for_source from toolsets import session_disabled_toolsets policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source) config = policy.config(authority, secrets=False) if policy is not None else {} enabled = list(policy.current_toolsets(config)) if policy is not None else None disabled = session_disabled_toolsets(parse_config_string_list((config.get('agent') or {}).get('disabled_toolsets')) or None, policy.platform if policy is not None else 'cli', oneshot=policy is not None and policy.source == 'oneshot') return enabled, disabled def _session_context(authority, ref): """The session vars a turn of this session binds (``GatewayRunner._session_env_scope``), so a re-mint carries the turn's caller identity and session key.""" from gateway.session import SessionContext from gateway.session_ancillary import physical_target live = authority.sessions[ref.session_id] context = SessionContext(source=live.source, connected_platforms=[], home_channels={}, session_key=live.route, session_id=physical_target(authority, ref)) return authority.runner._session_env_scope(context)