topos-node 0.1.0__py3-none-any.whl

topos/config/settings.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import List, Optional
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+DEFAULT_TOPOS_CONTROL_PLANE_URL = "wss://cp.logu3s.com/ws/engine"
+
+
+class Settings(BaseSettings):
+    """Topos settings sourced from environment."""
+
+    model_config = SettingsConfigDict(
+        env_file=Path(__file__).resolve().parent.parent / ".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    topos_key: Optional[str] = Field(None, env="TOPOS_KEY")
+    openai_api_key: Optional[str] = Field(None, env="OPENAI_API_KEY")
+
+    environment: str = Field("development", env="ENVIRONMENT")
+    log_format: Optional[str] = Field(None, env="LOG_FORMAT")
+    log_level: str = Field("DEBUG", env="LOG_LEVEL")
+
+    openai_base_url: str = Field("https://api.openai.com/v1", env="OPENAI_BASE_URL")
+    openai_model: str = Field("gpt-4o-mini", env="OPENAI_MODEL")
+
+    gt_cloud_api_key: Optional[str] = Field(None, env="GT_CLOUD_API_KEY")
+    griptape_nodes_api_base_url: str = Field(
+        "https://api.nodes.griptape.ai", env="GRIPTAPE_NODES_API_BASE_URL"
+    )
+
+    allowed_origins_raw: str = Field("http://localhost:3000", env="ALLOWED_ORIGINS")
+    allowed_origin_regex: Optional[str] = Field(None, env="ALLOWED_ORIGIN_REGEX")
+    enable_health_auth: bool = Field(False, env="ENABLE_HEALTH_AUTH")
+
+    request_timeout_seconds: float = Field(20.0, env="REQUEST_TIMEOUT_SECONDS")
+    openai_timeout_seconds: float = Field(15.0, env="OPENAI_TIMEOUT_SECONDS")
+    connection_retry_initial_seconds: float = Field(1.0, env="CONNECTION_RETRY_INITIAL_SECONDS")
+    connection_retry_max_seconds: float = Field(30.0, env="CONNECTION_RETRY_MAX_SECONDS")
+    connection_retry_jitter_ratio: float = Field(0.2, env="CONNECTION_RETRY_JITTER_RATIO")
+    connection_readiness_timeout_seconds: float = Field(15.0, env="CONNECTION_READINESS_TIMEOUT_SECONDS")
+    wait_for_control_plane_on_startup: bool = Field(False, env="WAIT_FOR_CONTROL_PLANE_ON_STARTUP")
+    wait_for_sync_on_startup: bool = Field(False, env="WAIT_FOR_SYNC_ON_STARTUP")
+    control_plane_inbound_concurrency_limit: int = Field(16, env="CONTROL_PLANE_INBOUND_CONCURRENCY_LIMIT")
+    control_plane_inbound_max_pending: int = Field(128, env="CONTROL_PLANE_INBOUND_MAX_PENDING")
+    control_plane_presence_outbox_size: int = Field(64, env="CONTROL_PLANE_PRESENCE_OUTBOX_SIZE")
+    sync_cursor_retry_attempts: int = Field(3, env="SYNC_CURSOR_RETRY_ATTEMPTS")
+    sync_cursor_retry_delay_seconds: float = Field(0.5, env="SYNC_CURSOR_RETRY_DELAY_SECONDS")
+
+    rate_limit_per_minute: int = Field(60, env="RATE_LIMIT_PER_MINUTE")
+    topos_control_plane_url: Optional[str] = Field(
+        DEFAULT_TOPOS_CONTROL_PLANE_URL, env="TOPOS_CONTROL_PLANE_URL"
+    )
+    control_plane_verify_ssl: bool = Field(True, env="CONTROL_PLANE_VERIFY_SSL")
+    hosted_pool_lease_enabled: bool = Field(False, env="HOSTED_POOL_LEASE_ENABLED")
+    hosted_pool_allow_static_key_in_cloud: bool = Field(
+        False, env="HOSTED_POOL_ALLOW_STATIC_KEY_IN_CLOUD"
+    )
+    hosted_pool_enforce_lease_in_cloud: bool = Field(
+        True, env="HOSTED_POOL_ENFORCE_LEASE_IN_CLOUD"
+    )
+    hosted_pool_lease_audience: Optional[str] = Field(None, env="HOSTED_POOL_LEASE_AUDIENCE")
+    hosted_pool_lease_issue_path: str = Field(
+        "/v1/system/pool-connectors/lease/issue", env="HOSTED_POOL_LEASE_ISSUE_PATH"
+    )
+    hosted_pool_lease_renew_path: str = Field(
+        "/v1/system/pool-connectors/lease/renew", env="HOSTED_POOL_LEASE_RENEW_PATH"
+    )
+    hosted_pool_lease_revoke_path: str = Field(
+        "/v1/system/pool-connectors/lease/revoke", env="HOSTED_POOL_LEASE_REVOKE_PATH"
+    )
+    hosted_pool_lease_pool_group: str = Field("default", env="HOSTED_POOL_LEASE_POOL_GROUP")
+    hosted_pool_lease_renew_skew_seconds: int = Field(60, env="HOSTED_POOL_LEASE_RENEW_SKEW_SECONDS")
+
+    engine_mode: str = Field("full", env="ENGINE_MODE")
+    enable_llm: bool = Field(True, env="ENABLE_LLM")
+    engine_transport_mode: str = Field("ws", env="ENGINE_TRANSPORT_MODE")
+    engine_name: Optional[str] = Field(None, env="ENGINE_NAME")
+    topos_compute_profile: str = Field("basic_hosted", env="TOPOS_COMPUTE_PROFILE")
+
+    engine_ollama_base_url: str = Field("http://localhost:11434", env="ENGINE_OLLAMA_BASE_URL")
+    engine_default_provider: str = Field("huggingface", env="ENGINE_DEFAULT_PROVIDER")
+
+    # Sanitization field-transforms via Ollama (see topos.config.sanitization_ollama + engine_config overrides)
+    sanitization_ollama_enabled: bool = Field(False, env="SANITIZATION_OLLAMA_ENABLED")
+    sanitization_ollama_host: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_HOST")
+    sanitization_ollama_default_model: str = Field("llama3.2", env="SANITIZATION_OLLAMA_DEFAULT_MODEL")
+    sanitization_ollama_timeout_sec: float = Field(120.0, env="SANITIZATION_OLLAMA_TIMEOUT_SEC")
+    sanitization_ollama_auto_pull: bool = Field(True, env="SANITIZATION_OLLAMA_AUTO_PULL")
+    sanitization_ollama_max_input_chars: int = Field(8000, env="SANITIZATION_OLLAMA_MAX_INPUT_CHARS")
+    sanitization_ollama_model_pii_redaction: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_PII_REDACTION")
+    sanitization_ollama_model_nsfw_sanitization: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_NSFW_SANITIZATION")
+    sanitization_ollama_model_raw_to_summary: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_RAW_TO_SUMMARY")
+    sanitization_ollama_model_raw_to_sentiment: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_RAW_TO_SENTIMENT")
+    sanitization_ollama_model_third_party_anonymization: Optional[str] = Field(
+        None, env="SANITIZATION_OLLAMA_MODEL_THIRD_PARTY_ANONYMIZATION"
+    )
+    sanitization_ollama_model_name_removal: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_NAME_REMOVAL")
+    sanitization_ollama_model_contact_removal: Optional[str] = Field(None, env="SANITIZATION_OLLAMA_MODEL_CONTACT_REMOVAL")
+
+    topos_database_path: Optional[str] = Field(None, env="TOPOS_DATABASE_PATH")
+    topos_database_mode: str = Field("local", env="TOPOS_DATABASE_MODE")
+    topos_database_service_url: Optional[str] = Field(None, env="TOPOS_DATABASE_SERVICE_URL")
+    topos_postgres_dsn: Optional[str] = Field(None, env="TOPOS_POSTGRES_DSN")
+    topos_postgres_host: Optional[str] = Field(None, env="TOPOS_POSTGRES_HOST")
+    topos_postgres_port: Optional[int] = Field(None, env="TOPOS_POSTGRES_PORT")
+    topos_postgres_db: Optional[str] = Field(None, env="TOPOS_POSTGRES_DB")
+    topos_postgres_user: Optional[str] = Field(None, env="TOPOS_POSTGRES_USER")
+    topos_postgres_password: Optional[str] = Field(None, env="TOPOS_POSTGRES_PASSWORD")
+    topos_postgres_reset_incompatible_schema: bool = Field(
+        False, env="TOPOS_POSTGRES_RESET_INCOMPATIBLE_SCHEMA"
+    )
+    topos_default_dataset_id: str = Field("default", env="TOPOS_DEFAULT_DATASET_ID")
+    topos_user_id: Optional[str] = Field(None, env="TOPOS_USER_ID")
+    # Pooled read enforcement mode for hosted shared-tenancy engines.
+    # "off" preserves legacy behavior; set to "pooled" to require tenant-scoped reads.
+    topos_pool_mode: str = Field("off", env="TOPOS_POOL_MODE")
+
+    topos_sync_url: str = Field("wss://cp.logu3s.com/ws/sync", env="TOPOS_SYNC_URL")
+    enable_sync: bool = Field(True, env="ENABLE_SYNC")
+
+    @property
+    def allowed_origins(self) -> List[str]:
+        raw = self.allowed_origins_raw
+        if not raw:
+            return []
+        if isinstance(raw, list):
+            return [str(o).strip() for o in raw if str(o).strip()]
+        raw_str = str(raw).strip()
+        if not raw_str:
+            return []
+        if raw_str.startswith("["):
+            try:
+                parsed = json.loads(raw_str)
+                if isinstance(parsed, list):
+                    return [str(o).strip() for o in parsed if str(o).strip()]
+            except json.JSONDecodeError:
+                pass
+        return [o.strip() for o in raw_str.split(",") if o.strip()]
+
+    def get_sync_url(self) -> str:
+        """Get sync URL (defaults to wss://cp.logu3s.com/ws/sync)."""
+        return self.topos_sync_url
+
+    @property
+    def control_plane_url(self) -> Optional[str]:
+        return self.topos_control_plane_url
+
+    @control_plane_url.setter
+    def control_plane_url(self, value: Optional[str]) -> None:
+        self.topos_control_plane_url = value
+
+    @property
+    def database_path(self) -> Optional[str]:
+        return self.topos_database_path
+
+    @database_path.setter
+    def database_path(self, value: Optional[str]) -> None:
+        self.topos_database_path = value
+
+    @property
+    def database_mode(self) -> str:
+        return self.topos_database_mode
+
+    @database_mode.setter
+    def database_mode(self, value: str) -> None:
+        self.topos_database_mode = value
+
+    @property
+    def database_service_url(self) -> Optional[str]:
+        return self.topos_database_service_url
+
+    @database_service_url.setter
+    def database_service_url(self, value: Optional[str]) -> None:
+        self.topos_database_service_url = value
+
+    @property
+    def postgres_dsn(self) -> Optional[str]:
+        return self.topos_postgres_dsn
+
+    @postgres_dsn.setter
+    def postgres_dsn(self, value: Optional[str]) -> None:
+        self.topos_postgres_dsn = value
+
+    @property
+    def postgres_host(self) -> Optional[str]:
+        return self.topos_postgres_host
+
+    @postgres_host.setter
+    def postgres_host(self, value: Optional[str]) -> None:
+        self.topos_postgres_host = value
+
+    @property
+    def postgres_port(self) -> Optional[int]:
+        return self.topos_postgres_port
+
+    @postgres_port.setter
+    def postgres_port(self, value: Optional[int]) -> None:
+        self.topos_postgres_port = value
+
+    @property
+    def postgres_db(self) -> Optional[str]:
+        return self.topos_postgres_db
+
+    @postgres_db.setter
+    def postgres_db(self, value: Optional[str]) -> None:
+        self.topos_postgres_db = value
+
+    @property
+    def postgres_user(self) -> Optional[str]:
+        return self.topos_postgres_user
+
+    @postgres_user.setter
+    def postgres_user(self, value: Optional[str]) -> None:
+        self.topos_postgres_user = value
+
+    @property
+    def postgres_password(self) -> Optional[str]:
+        return self.topos_postgres_password
+
+    @postgres_password.setter
+    def postgres_password(self, value: Optional[str]) -> None:
+        self.topos_postgres_password = value
+
+    @property
+    def postgres_reset_incompatible_schema(self) -> bool:
+        return self.topos_postgres_reset_incompatible_schema
+
+    @postgres_reset_incompatible_schema.setter
+    def postgres_reset_incompatible_schema(self, value: bool) -> None:
+        self.topos_postgres_reset_incompatible_schema = value
+
+    @property
+    def default_dataset_id(self) -> str:
+        return self.topos_default_dataset_id
+
+    @default_dataset_id.setter
+    def default_dataset_id(self, value: str) -> None:
+        self.topos_default_dataset_id = value
+
+    @property
+    def user_id(self) -> Optional[str]:
+        return self.topos_user_id
+
+    @user_id.setter
+    def user_id(self, value: Optional[str]) -> None:
+        self.topos_user_id = value
+
+    @property
+    def engine_pool_mode(self) -> str:
+        return self.topos_pool_mode
+
+    @engine_pool_mode.setter
+    def engine_pool_mode(self, value: str) -> None:
+        self.topos_pool_mode = value
+
+    @property
+    def sync_url(self) -> str:
+        return self.topos_sync_url
+
+    @sync_url.setter
+    def sync_url(self, value: str) -> None:
+        self.topos_sync_url = value
+
+    @model_validator(mode="after")
+    def _validate_topos_key_or_lease(self) -> "Settings":
+        is_cloud_runtime = bool(
+            os.getenv("K_SERVICE")
+            or os.getenv("K_REVISION")
+            or os.getenv("CLOUD_RUN_JOB")
+        )
+        lease_env_explicit = os.getenv("HOSTED_POOL_LEASE_ENABLED") is not None
+
+        if is_cloud_runtime and self.topos_control_plane_url and not lease_env_explicit:
+            # Cloud-hosted runtimes should default to lease-based connector identities
+            # unless an operator explicitly sets HOSTED_POOL_LEASE_ENABLED.
+            self.hosted_pool_lease_enabled = True
+
+        if (
+            is_cloud_runtime
+            and self.topos_control_plane_url
+            and self.topos_key
+            and not self.hosted_pool_lease_enabled
+            and self.hosted_pool_enforce_lease_in_cloud
+            and not self.hosted_pool_allow_static_key_in_cloud
+        ):
+            raise ValueError(
+                "Cloud runtime requires hosted pool lease mode by default. "
+                "Set HOSTED_POOL_LEASE_ENABLED=true, or set "
+                "HOSTED_POOL_ALLOW_STATIC_KEY_IN_CLOUD=true for break-glass static key mode."
+            )
+
+        if self.topos_key:
+            return self
+        if self.hosted_pool_lease_enabled and self.topos_control_plane_url:
+            return self
+        raise ValueError(
+            "TOPOS_KEY is required unless HOSTED_POOL_LEASE_ENABLED=true and TOPOS_CONTROL_PLANE_URL is configured."
+        )
+
+
+settings = Settings()

topos/contacts/__init__.py

@@ -0,0 +1,5 @@
+"""Contact identity helpers for messenger / UMA (Stage 11)."""
+
+from topos.contacts.identity import normalize_contact_key
+
+__all__ = ["normalize_contact_key"]

topos/contacts/identity.py

@@ -0,0 +1,24 @@
+"""Normalize sender / identifier strings for matching contact_identifiers rows."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def normalize_contact_key(value: Any) -> str:
+    """
+    Match keys used when joining message sender_id to contact book identifiers.
+    Aligned with historical logic in topos.core.handlers._normalize_contact_key.
+    """
+    s = str(value or "").strip()
+    if not s:
+        return ""
+    low = s.lower()
+    if low == "self":
+        return "self"
+    if "@" in low:
+        return low
+    digits = "".join(ch for ch in s if ch.isdigit())
+    if digits:
+        return f"+{digits}" if s.startswith("+") else digits
+    return low

topos/control_plane_client.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections import deque
+import json
+import logging
+import ssl
+from typing import Any, Awaitable, Callable, Dict
+
+import certifi
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed
+
+from .config.settings import settings
+from .core.connection_resilience import (
+    ConnectionSnapshot,
+    ConnectionState,
+    ExponentialBackoff,
+    FailureCategory,
+    ResilienceConfig,
+    classify_connection_error,
+    is_fatal_connection_category,
+    utc_now_iso,
+)
+
+logger = logging.getLogger("topos.control_plane_client")
+
+
+class ControlPlaneClient:
+    """Maintains a WS connection to the control plane and dispatches incoming requests."""
+
+    def __init__(
+        self,
+        control_plane_url: str,
+        api_key: str,
+        handler: Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]],
+        verify_ssl: bool = True,
+    ):
+        self.control_plane_url = control_plane_url
+        self.api_key = api_key
+        self.handler = handler
+        self.verify_ssl = verify_ssl
+        self._task: asyncio.Task | None = None
+        self._stop = asyncio.Event()
+        self._ws = None
+        self._state: ConnectionState = "idle"
+        self._state_changed_at: str | None = utc_now_iso()
+        self._last_connected_at: str | None = None
+        self._last_disconnected_at: str | None = None
+        self._last_failure_category: FailureCategory = "none"
+        self._last_failure_reason: str = ""
+        self._attempt = 0
+        self._consecutive_failures = 0
+        self._ready = asyncio.Event()
+
+        self._inbound_concurrency_limit = max(1, int(settings.control_plane_inbound_concurrency_limit))
+        self._inbound_max_pending = max(
+            self._inbound_concurrency_limit,
+            int(settings.control_plane_inbound_max_pending),
+        )
+        self._inbound_semaphore = asyncio.Semaphore(self._inbound_concurrency_limit)
+        self._inbound_tasks: set[asyncio.Task] = set()
+        self._inbound_lock = asyncio.Lock()
+
+        self._presence_outbox_size = max(1, int(settings.control_plane_presence_outbox_size))
+        self._presence_outbox: deque[dict[str, Any]] = deque(maxlen=self._presence_outbox_size)
+        self._outbox_lock = asyncio.Lock()
+
+        self._backoff = ExponentialBackoff(
+            ResilienceConfig(
+                initial_backoff_s=max(0.1, float(settings.connection_retry_initial_seconds)),
+                max_backoff_s=max(1.0, float(settings.connection_retry_max_seconds)),
+                jitter_ratio=max(0.0, float(settings.connection_retry_jitter_ratio)),
+            )
+        )
+
+    def _set_state(self, state: ConnectionState) -> None:
+        if self._state == state:
+            return
+        self._state = state
+        self._state_changed_at = utc_now_iso()
+
+    def get_connection_status(self) -> dict[str, Any]:
+        snapshot = ConnectionSnapshot(
+            state=self._state,
+            connected=bool(self._ws),
+            attempt=self._attempt,
+            consecutive_failures=self._consecutive_failures,
+            last_failure_category=self._last_failure_category,
+            last_failure_reason=self._last_failure_reason,
+            last_state_change_at=self._state_changed_at,
+            last_connected_at=self._last_connected_at,
+            last_disconnected_at=self._last_disconnected_at,
+            outbox_depth=len(self._presence_outbox),
+        )
+        return snapshot.to_dict()
+
+    def start(self) -> None:
+        if self._task and not self._task.done():
+            return
+        self._stop.clear()
+        self._task = asyncio.create_task(self._run())
+        logger.info("Control plane client starting: %s", self.control_plane_url)
+
+    async def wait_until_connected(self, timeout_s: float | None = None) -> bool:
+        timeout = float(timeout_s) if timeout_s is not None else float(settings.connection_readiness_timeout_seconds)
+        try:
+            await asyncio.wait_for(self._ready.wait(), timeout=max(0.1, timeout))
+            return True
+        except TimeoutError:
+            return False
+
+    async def stop(self) -> None:
+        self._set_state("stopping")
+        self._stop.set()
+        if self._ws:
+            try:
+                await self._ws.close(code=1000)
+            except Exception:
+                pass
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        await self._cancel_inbound_tasks()
+        self._ws = None
+        self._ready.clear()
+        self._set_state("idle")
+
+    async def _cancel_inbound_tasks(self) -> None:
+        async with self._inbound_lock:
+            pending = list(self._inbound_tasks)
+        for task in pending:
+            task.cancel()
+        for task in pending:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+    async def _run(self) -> None:
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        ssl_context = None
+        if self.control_plane_url.startswith("wss://"):
+            ssl_context = ssl.create_default_context(cafile=certifi.where())
+            if not self.verify_ssl:
+                ssl_context.check_hostname = False
+                ssl_context.verify_mode = ssl.CERT_NONE
+        while not self._stop.is_set():
+            self._set_state("connecting")
+            self._attempt += 1
+            try:
+                async with connect(
+                    self.control_plane_url,
+                    additional_headers=headers,
+                    ssl=ssl_context,
+                    # Transform-heavy requests can block the event loop in the handler path long enough
+                    # to miss pong deadlines; disable pong timeout-driven disconnects.
+                    ping_timeout=None,
+                ) as ws:
+                    self._ws = ws
+                    self._set_state("connected")
+                    self._ready.set()
+                    self._backoff.reset()
+                    self._last_failure_category = "none"
+                    self._last_failure_reason = ""
+                    self._consecutive_failures = 0
+                    self._last_connected_at = utc_now_iso()
+                    logger.info("Control plane client connected")
+                    await self._flush_presence_outbox()
+                    async for raw in ws:
+                        if self._stop.is_set():
+                            break
+                        try:
+                            data = json.loads(raw)
+                        except Exception:
+                            logger.warning("Relay message is not valid JSON: %s", raw)
+                            continue
+                        await self._schedule_inbound_message(ws, data)
+            except ConnectionClosed as exc:
+                self._record_failure(exc)
+            except Exception as exc:  # noqa: BLE001
+                self._record_failure(exc)
+            finally:
+                self._ws = None
+                self._ready.clear()
+                if not self._stop.is_set() and self._state != "stopping":
+                    self._last_disconnected_at = utc_now_iso()
+            if self._stop.is_set():
+                break
+            delay = self._backoff.next_delay()
+            self._set_state("degraded" if is_fatal_connection_category(self._last_failure_category) else "backing_off")
+            logger.warning(
+                "Control plane reconnect scheduled endpoint=%s state=%s attempt=%d failures=%d category=%s delay_s=%.2f reason=%s",
+                self.control_plane_url,
+                self._state,
+                self._attempt,
+                self._consecutive_failures,
+                self._last_failure_category,
+                delay,
+                self._last_failure_reason,
+            )
+            await self._wait_for_stop_or_timeout(delay)
+        self._set_state("idle")
+
+    def _record_failure(self, exc: BaseException) -> None:
+        category, reason = classify_connection_error(exc)
+        self._last_failure_category = category
+        self._last_failure_reason = reason
+        self._consecutive_failures += 1
+        logger.warning(
+            "Control plane connectivity event endpoint=%s event=connection_failed category=%s failures=%d reason=%s",
+            self.control_plane_url,
+            category,
+            self._consecutive_failures,
+            reason,
+        )
+
+    async def _wait_for_stop_or_timeout(self, timeout_s: float) -> None:
+        try:
+            await asyncio.wait_for(self._stop.wait(), timeout=timeout_s)
+        except TimeoutError:
+            return
+
+    async def _schedule_inbound_message(self, ws, data: Dict[str, Any]) -> None:
+        async with self._inbound_lock:
+            pending_count = len(self._inbound_tasks)
+            if pending_count >= self._inbound_max_pending:
+                logger.warning("Dropping inbound request due to saturation pending=%d", pending_count)
+                request_id = data.get("id")
+                if request_id:
+                    await self._send_ws_json(
+                        ws,
+                        {"id": request_id, "status": "error", "error": "Engine is busy. Retry shortly."},
+                    )
+                return
+            task = asyncio.create_task(self._handle_message_guarded(ws, data))
+            self._inbound_tasks.add(task)
+            task.add_done_callback(self._on_inbound_task_done)
+
+    def _on_inbound_task_done(self, task: asyncio.Task) -> None:
+        self._inbound_tasks.discard(task)
+
+    async def _handle_message_guarded(self, ws, data: Dict[str, Any]) -> None:
+        async with self._inbound_semaphore:
+            await self._handle_message(ws, data)
+
+    async def _flush_presence_outbox(self) -> None:
+        async with self._outbox_lock:
+            pending = list(self._presence_outbox)
+            self._presence_outbox.clear()
+        if not pending:
+            return
+        for message in pending:
+            success = await self._send_ws_json(self._ws, message)
+            if not success:
+                await self._enqueue_presence_message(message)
+                break
+
+    async def _enqueue_presence_message(self, message: Dict[str, Any]) -> None:
+        async with self._outbox_lock:
+            at_capacity = len(self._presence_outbox) >= self._presence_outbox_size
+            if at_capacity:
+                dropped = self._presence_outbox.popleft()
+                logger.warning(
+                    "Presence outbox full; dropping oldest message type=%s",
+                    dropped.get("type"),
+                )
+            self._presence_outbox.append(dict(message))
+
+    async def _send_ws_json(self, ws, payload: Dict[str, Any]) -> bool:
+        if not ws:
+            return False
+        try:
+            await ws.send(json.dumps(payload))
+            return True
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to send message to control plane: %s", exc)
+            return False
+
+    async def _handle_message(self, ws, data: Dict[str, Any]) -> None:
+        try:
+            resp = await self.handler(data)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Handler raised exception: %s", exc, exc_info=True)
+            resp = {"id": data.get("id"), "status": "error", "error": str(exc)}
+        if resp is None:
+            return  # e.g. connection_info or message without id; CP has no pending request to match
+        await self._send_ws_json(ws, resp)
+
+    async def send_message(self, message: Dict[str, Any]) -> None:
+        """Send an unsolicited message to the control plane (e.g., progress updates)."""
+        if not self._ws:
+            await self._enqueue_presence_message(message)
+            logger.warning("Queued presence message; control plane currently disconnected")
+            return
+        sent = await self._send_ws_json(self._ws, message)
+        if not sent:
+            await self._enqueue_presence_message(message)

topos/core/__init__.py

@@ -0,0 +1 @@
+"""Core utilities for Topos."""