feat: UserAvatar (#9527)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/onyx/background/celery/tasks/beat_schedule.py

@@ -9,12 +9,12 @@ from onyx.configs.app_configs import AUTO_LLM_UPDATE_INTERVAL_SECONDS
 from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.app_configs import ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
 from onyx.configs.app_configs import ENTERPRISE_EDITION_ENABLED
-from onyx.configs.app_configs import HOOK_ENABLED
 from onyx.configs.app_configs import SCHEDULED_EVAL_DATASET_NAMES
 from onyx.configs.constants import ONYX_CLOUD_CELERY_TASK_PREFIX
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
 from onyx.configs.constants import OnyxCeleryTask
+from onyx.hooks.utils import HOOKS_AVAILABLE
 from shared_configs.configs import MULTI_TENANT
 
 # choosing 15 minutes because it roughly gives us enough time to process many tasks
@@ -362,7 +362,7 @@ if not MULTI_TENANT:
 
     tasks_to_schedule.extend(beat_task_templates)
 
-if not MULTI_TENANT and HOOK_ENABLED:
+if HOOKS_AVAILABLE:
     tasks_to_schedule.append(
         {
             "name": "hook-execution-log-cleanup",

backend/onyx/chat/chat_utils.py

@@ -30,6 +30,8 @@ from onyx.file_processing.extract_file_text import extract_file_text
 from onyx.file_store.file_store import get_default_file_store
 from onyx.file_store.models import ChatFileType
 from onyx.file_store.models import FileDescriptor
+from onyx.file_store.utils import plaintext_file_name_for_id
+from onyx.file_store.utils import store_plaintext
 from onyx.kg.models import KGException
 from onyx.kg.setup.kg_default_entity_definitions import (
     populate_missing_default_entity_types__commit,
@@ -289,6 +291,33 @@ def process_kg_commands(
         raise KGException("KG setup done")
 
 
+def _get_or_extract_plaintext(
+    file_id: str,
+    extract_fn: Callable[[], str],
+) -> str:
+    """Load cached plaintext for a file, or extract and store it.
+
+    Tries to read pre-stored plaintext from the file store.  On a miss,
+    calls extract_fn to produce the text, then stores the result so
+    future calls skip the expensive extraction.
+    """
+    file_store = get_default_file_store()
+    plaintext_key = plaintext_file_name_for_id(file_id)
+
+    # Try cached plaintext first.
+    try:
+        plaintext_io = file_store.read_file(plaintext_key, mode="b")
+        return plaintext_io.read().decode("utf-8")
+    except Exception:
+        logger.exception(f"Error when reading file, id={file_id}")
+
+    # Cache miss — extract and store.
+    content_text = extract_fn()
+    if content_text:
+        store_plaintext(file_id, content_text)
+    return content_text
+
+
 @log_function_time(print_only=True)
 def load_chat_file(
     file_descriptor: FileDescriptor, db_session: Session
@@ -303,12 +332,23 @@ def load_chat_file(
     file_type = ChatFileType(file_descriptor["type"])
 
     if file_type.is_text_file():
-        try:
-            content_text = extract_file_text(
+        file_id = file_descriptor["id"]
+
+        def _extract() -> str:
+            return extract_file_text(
                 file=file_io,
                 file_name=file_descriptor.get("name") or "",
                 break_on_unprocessable=False,
             )
+
+        # Use the user_file_id as cache key when available (matches what
+        # the celery indexing worker stores), otherwise fall back to the
+        # file store id (covers code-interpreter-generated files, etc.).
+        user_file_id_str = file_descriptor.get("user_file_id")
+        cache_key = user_file_id_str or file_id
+
+        try:
+            content_text = _get_or_extract_plaintext(cache_key, _extract)
         except Exception as e:
             logger.warning(
                 f"Failed to retrieve content for file {file_descriptor['id']}: {str(e)}"

backend/onyx/db/swap_index.py

@@ -2,6 +2,7 @@ import time
 
 from sqlalchemy.orm import Session
 
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.app_configs import VESPA_NUM_ATTEMPTS_ON_STARTUP
 from onyx.configs.constants import KV_REINDEX_KEY
 from onyx.db.connector_credential_pair import get_connector_credential_pairs
@@ -149,6 +150,9 @@ def check_and_perform_index_swap(db_session: Session) -> SearchSettings | None:
     Returns None if search settings did not change, or the old search settings if they
     did change.
     """
+    if DISABLE_VECTOR_DB:
+        return None
+
     # Default CC-pair created for Ingestion API unused here
     all_cc_pairs = get_connector_credential_pairs(db_session)
     cc_pair_count = max(len(all_cc_pairs) - 1, 0)

backend/onyx/error_handling/error_codes.py

@@ -88,6 +88,7 @@ class OnyxErrorCode(Enum):
     SERVICE_UNAVAILABLE = ("SERVICE_UNAVAILABLE", 503)
     BAD_GATEWAY = ("BAD_GATEWAY", 502)
     LLM_PROVIDER_ERROR = ("LLM_PROVIDER_ERROR", 502)
+    HOOK_EXECUTION_FAILED = ("HOOK_EXECUTION_FAILED", 502)
     GATEWAY_TIMEOUT = ("GATEWAY_TIMEOUT", 504)
 
     def __init__(self, code: str, status_code: int) -> None:

backend/onyx/file_store/utils.py

@@ -23,45 +23,55 @@ from onyx.utils.timing import log_function_time
 logger = setup_logger()
 
 
-def user_file_id_to_plaintext_file_name(user_file_id: UUID) -> str:
-    """Generate a consistent file name for storing plaintext content of a user file."""
-    return f"plaintext_{user_file_id}"
+def plaintext_file_name_for_id(file_id: str) -> str:
+    """Generate a consistent file name for storing plaintext content of a file."""
+    return f"plaintext_{file_id}"
 
 
-def store_user_file_plaintext(user_file_id: UUID, plaintext_content: str) -> bool:
+def store_plaintext(file_id: str, plaintext_content: str) -> bool:
     """
-    Store plaintext content for a user file in the file store.
+    Store plaintext content for a file in the file store.
 
     Args:
-        user_file_id: The ID of the user file
+        file_id: The ID of the file (user_file or artifact_file)
         plaintext_content: The plaintext content to store
 
     Returns:
         bool: True if storage was successful, False otherwise
     """
-    # Skip empty content
     if not plaintext_content:
         return False
 
-    # Get plaintext file name
-    plaintext_file_name = user_file_id_to_plaintext_file_name(user_file_id)
-
+    plaintext_file_name = plaintext_file_name_for_id(file_id)
     try:
         file_store = get_default_file_store()
         file_content = BytesIO(plaintext_content.encode("utf-8"))
         file_store.save_file(
             content=file_content,
-            display_name=f"Plaintext for user file {user_file_id}",
+            display_name=f"Plaintext for {file_id}",
             file_origin=FileOrigin.PLAINTEXT_CACHE,
             file_type="text/plain",
             file_id=plaintext_file_name,
         )
         return True
     except Exception as e:
-        logger.warning(f"Failed to store plaintext for user file {user_file_id}: {e}")
+        logger.warning(f"Failed to store plaintext for {file_id}: {e}")
         return False
 
 
+# --- Convenience wrappers for callers that use user-file UUIDs ---
+
+
+def user_file_id_to_plaintext_file_name(user_file_id: UUID) -> str:
+    """Generate a consistent file name for storing plaintext content of a user file."""
+    return plaintext_file_name_for_id(str(user_file_id))
+
+
+def store_user_file_plaintext(user_file_id: UUID, plaintext_content: str) -> bool:
+    """Store plaintext content for a user file (delegates to :func:`store_plaintext`)."""
+    return store_plaintext(str(user_file_id), plaintext_content)
+
+
 def load_chat_file_by_id(file_id: str) -> InMemoryChatFile:
     """Load a file directly from the file store using its file_record ID.
 

backend/onyx/hooks/executor.py

@@ -0,0 +1,330 @@
+"""Hook executor — calls a customer's external HTTP endpoint for a given hook point.
+
+Usage (Celery tasks and FastAPI handlers):
+    result = execute_hook(
+        db_session=db_session,
+        hook_point=HookPoint.QUERY_PROCESSING,
+        payload={"query": "...", "user_email": "...", "chat_session_id": "..."},
+    )
+
+    if isinstance(result, HookSkipped):
+        # no active hook configured — continue with original behavior
+        ...
+    elif isinstance(result, HookSoftFailed):
+        # hook failed but fail strategy is SOFT — continue with original behavior
+        ...
+    else:
+        # result is the response payload dict from the customer's endpoint
+        ...
+
+is_reachable update policy
+--------------------------
+``is_reachable`` on the Hook row is updated selectively — only when the outcome
+carries meaningful signal about physical reachability:
+
+  NetworkError (DNS, connection refused)  → False  (cannot reach the server)
+  HTTP 401 / 403                          → False  (api_key revoked or invalid)
+  TimeoutException                        → None   (server may be slow, skip write)
+  Other HTTP errors (4xx / 5xx)           → None   (server responded, skip write)
+  Unknown exception                       → None   (no signal, skip write)
+  Non-JSON / non-dict response            → None   (server responded, skip write)
+  Success (2xx, valid dict)               → True   (confirmed reachable)
+
+None means "leave the current value unchanged" — no DB round-trip is made.
+
+DB session design
+-----------------
+The executor uses three sessions:
+
+  1. Caller's session (db_session) — used only for the hook lookup read. All
+     needed fields are extracted from the Hook object before the HTTP call, so
+     the caller's session is not held open during the external HTTP request.
+
+  2. Log session — a separate short-lived session opened after the HTTP call
+     completes to write the HookExecutionLog row on failure. Success runs are
+     not recorded. Committed independently of everything else.
+
+  3. Reachable session — a second short-lived session to update is_reachable on
+     the Hook. Kept separate from the log session so a concurrent hook deletion
+     (which causes update_hook__no_commit to raise OnyxError(NOT_FOUND)) cannot
+     prevent the execution log from being written. This update is best-effort.
+"""
+
+import json
+import time
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from onyx.db.engine.sql_engine import get_session_with_current_tenant
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.db.hook import create_hook_execution_log__no_commit
+from onyx.db.hook import get_non_deleted_hook_by_hook_point
+from onyx.db.hook import update_hook__no_commit
+from onyx.db.models import Hook
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.hooks.utils import HOOKS_AVAILABLE
+from onyx.utils.logger import setup_logger
+
+logger = setup_logger()
+
+
+class HookSkipped:
+    """No active hook configured for this hook point."""
+
+
+class HookSoftFailed:
+    """Hook was called but failed with SOFT fail strategy — continuing."""
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+class _HttpOutcome(BaseModel):
+    """Structured result of an HTTP hook call, returned by _process_response."""
+
+    is_success: bool
+    updated_is_reachable: (
+        bool | None
+    )  # True/False = write to DB, None = unchanged (skip write)
+    status_code: int | None
+    error_message: str | None
+    response_payload: dict[str, Any] | None
+
+
+def _lookup_hook(
+    db_session: Session,
+    hook_point: HookPoint,
+) -> Hook | HookSkipped:
+    """Return the active Hook or HookSkipped if hooks are unavailable/unconfigured.
+
+    No HTTP call is made and no DB writes are performed for any HookSkipped path.
+    There is nothing to log and no reachability information to update.
+    """
+    if not HOOKS_AVAILABLE:
+        return HookSkipped()
+    hook = get_non_deleted_hook_by_hook_point(
+        db_session=db_session, hook_point=hook_point
+    )
+    if hook is None or not hook.is_active:
+        return HookSkipped()
+    if not hook.endpoint_url:
+        return HookSkipped()
+    return hook
+
+
+def _process_response(
+    *,
+    response: httpx.Response | None,
+    exc: Exception | None,
+    timeout: float,
+) -> _HttpOutcome:
+    """Process the result of an HTTP call and return a structured outcome.
+
+    Called after the client.post() try/except. If post() raised, exc is set and
+    response is None. Otherwise response is set and exc is None. Handles
+    raise_for_status(), JSON decoding, and the dict shape check.
+    """
+    if exc is not None:
+        if isinstance(exc, httpx.NetworkError):
+            msg = f"Hook network error (endpoint unreachable): {exc}"
+            logger.warning(msg, exc_info=exc)
+            return _HttpOutcome(
+                is_success=False,
+                updated_is_reachable=False,
+                status_code=None,
+                error_message=msg,
+                response_payload=None,
+            )
+        if isinstance(exc, httpx.TimeoutException):
+            msg = f"Hook timed out after {timeout}s: {exc}"
+            logger.warning(msg, exc_info=exc)
+            return _HttpOutcome(
+                is_success=False,
+                updated_is_reachable=None,  # timeout doesn't indicate unreachability
+                status_code=None,
+                error_message=msg,
+                response_payload=None,
+            )
+        msg = f"Hook call failed: {exc}"
+        logger.exception(msg, exc_info=exc)
+        return _HttpOutcome(
+            is_success=False,
+            updated_is_reachable=None,  # unknown error — don't make assumptions
+            status_code=None,
+            error_message=msg,
+            response_payload=None,
+        )
+
+    if response is None:
+        raise ValueError(
+            "exactly one of response or exc must be non-None; both are None"
+        )
+    status_code = response.status_code
+
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as e:
+        msg = f"Hook returned HTTP {e.response.status_code}: {e.response.text}"
+        logger.warning(msg, exc_info=e)
+        # 401/403 means the api_key has been revoked or is invalid — mark unreachable
+        # so the operator knows to update it. All other HTTP errors keep is_reachable
+        # as-is (server is up, the request just failed for application reasons).
+        auth_failed = e.response.status_code in (401, 403)
+        return _HttpOutcome(
+            is_success=False,
+            updated_is_reachable=False if auth_failed else None,
+            status_code=status_code,
+            error_message=msg,
+            response_payload=None,
+        )
+
+    try:
+        response_payload = response.json()
+    except (json.JSONDecodeError, httpx.DecodingError) as e:
+        msg = f"Hook returned non-JSON response: {e}"
+        logger.warning(msg, exc_info=e)
+        return _HttpOutcome(
+            is_success=False,
+            updated_is_reachable=None,  # server responded — reachability unchanged
+            status_code=status_code,
+            error_message=msg,
+            response_payload=None,
+        )
+
+    if not isinstance(response_payload, dict):
+        msg = f"Hook returned non-dict JSON (got {type(response_payload).__name__})"
+        logger.warning(msg)
+        return _HttpOutcome(
+            is_success=False,
+            updated_is_reachable=None,  # server responded — reachability unchanged
+            status_code=status_code,
+            error_message=msg,
+            response_payload=None,
+        )
+
+    return _HttpOutcome(
+        is_success=True,
+        updated_is_reachable=True,
+        status_code=status_code,
+        error_message=None,
+        response_payload=response_payload,
+    )
+
+
+def _persist_result(
+    *,
+    hook_id: int,
+    outcome: _HttpOutcome,
+    duration_ms: int,
+) -> None:
+    """Write the execution log on failure and optionally update is_reachable, each
+    in its own session so a failure in one does not affect the other."""
+    # Only write the execution log on failure — success runs are not recorded.
+    # Must not be skipped if the is_reachable update fails (e.g. hook concurrently
+    # deleted between the initial lookup and here).
+    if not outcome.is_success:
+        try:
+            with get_session_with_current_tenant() as log_session:
+                create_hook_execution_log__no_commit(
+                    db_session=log_session,
+                    hook_id=hook_id,
+                    is_success=False,
+                    error_message=outcome.error_message,
+                    status_code=outcome.status_code,
+                    duration_ms=duration_ms,
+                )
+                log_session.commit()
+        except Exception:
+            logger.exception(
+                f"Failed to persist hook execution log for hook_id={hook_id}"
+            )
+
+    # Update is_reachable separately — best-effort, non-critical.
+    # None means the value is unchanged (set by the caller to skip the no-op write).
+    # update_hook__no_commit can raise OnyxError(NOT_FOUND) if the hook was
+    # concurrently deleted, so keep this isolated from the log write above.
+    if outcome.updated_is_reachable is not None:
+        try:
+            with get_session_with_current_tenant() as reachable_session:
+                update_hook__no_commit(
+                    db_session=reachable_session,
+                    hook_id=hook_id,
+                    is_reachable=outcome.updated_is_reachable,
+                )
+                reachable_session.commit()
+        except Exception:
+            logger.warning(f"Failed to update is_reachable for hook_id={hook_id}")
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def execute_hook(
+    *,
+    db_session: Session,
+    hook_point: HookPoint,
+    payload: dict[str, Any],
+) -> dict[str, Any] | HookSkipped | HookSoftFailed:
+    """Execute the hook for the given hook point synchronously."""
+    hook = _lookup_hook(db_session, hook_point)
+    if isinstance(hook, HookSkipped):
+        return hook
+
+    timeout = hook.timeout_seconds
+    hook_id = hook.id
+    fail_strategy = hook.fail_strategy
+    endpoint_url = hook.endpoint_url
+    current_is_reachable: bool | None = hook.is_reachable
+    if not endpoint_url:
+        raise ValueError(
+            f"hook_id={hook_id} is active but has no endpoint_url — "
+            "active hooks without an endpoint_url must be rejected by _lookup_hook"
+        )
+
+    start = time.monotonic()
+    response: httpx.Response | None = None
+    exc: Exception | None = None
+    try:
+        api_key: str | None = (
+            hook.api_key.get_value(apply_mask=False) if hook.api_key else None
+        )
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        with httpx.Client(timeout=timeout) as client:
+            response = client.post(endpoint_url, json=payload, headers=headers)
+    except Exception as e:
+        exc = e
+    duration_ms = int((time.monotonic() - start) * 1000)
+
+    outcome = _process_response(response=response, exc=exc, timeout=timeout)
+    # Skip the is_reachable write when the value would not change — avoids a
+    # no-op DB round-trip on every call when the hook is already in the expected state.
+    if outcome.updated_is_reachable == current_is_reachable:
+        outcome = outcome.model_copy(update={"updated_is_reachable": None})
+    _persist_result(hook_id=hook_id, outcome=outcome, duration_ms=duration_ms)
+
+    if not outcome.is_success:
+        if fail_strategy == HookFailStrategy.HARD:
+            raise OnyxError(
+                OnyxErrorCode.HOOK_EXECUTION_FAILED,
+                outcome.error_message or "Hook execution failed.",
+            )
+        logger.warning(
+            f"Hook execution failed (soft fail) for hook_id={hook_id}: {outcome.error_message}"
+        )
+        return HookSoftFailed()
+    if outcome.response_payload is None:
+        raise ValueError(
+            f"response_payload is None for successful hook call (hook_id={hook_id})"
+        )
+    return outcome.response_payload

backend/onyx/hooks/models.py

@@ -42,12 +42,8 @@ class HookUpdateRequest(BaseModel):
     name: str | None = None
     endpoint_url: str | None = None
     api_key: NonEmptySecretStr | None = None
-    fail_strategy: HookFailStrategy | None = (
-        None  # if None in model_fields_set, reset to spec default
-    )
-    timeout_seconds: float | None = Field(
-        default=None, gt=0
-    )  # if None in model_fields_set, reset to spec default
+    fail_strategy: HookFailStrategy | None = None
+    timeout_seconds: float | None = Field(default=None, gt=0)
 
     @model_validator(mode="after")
     def require_at_least_one_field(self) -> "HookUpdateRequest":
@@ -60,6 +56,14 @@ class HookUpdateRequest(BaseModel):
             and not (self.endpoint_url or "").strip()
         ):
             raise ValueError("endpoint_url cannot be cleared.")
+        if "fail_strategy" in self.model_fields_set and self.fail_strategy is None:
+            raise ValueError(
+                "fail_strategy cannot be null; omit the field to leave it unchanged."
+            )
+        if "timeout_seconds" in self.model_fields_set and self.timeout_seconds is None:
+            raise ValueError(
+                "timeout_seconds cannot be null; omit the field to leave it unchanged."
+            )
         return self
 
 
@@ -90,38 +94,28 @@ class HookResponse(BaseModel):
     fail_strategy: HookFailStrategy
     timeout_seconds: float  # always resolved — None from request is replaced with spec default before DB write
     is_active: bool
+    is_reachable: bool | None
     creator_email: str | None
     created_at: datetime
     updated_at: datetime
 
 
+class HookValidateStatus(str, Enum):
+    passed = "passed"  # server responded (any status except 401/403)
+    auth_failed = "auth_failed"  # server responded with 401 or 403
+    timeout = (
+        "timeout"  # TCP connected, but read/write timed out (server exists but slow)
+    )
+    cannot_connect = "cannot_connect"  # could not connect to the server
+
+
 class HookValidateResponse(BaseModel):
-    success: bool
+    status: HookValidateStatus
     error_message: str | None = None
 
 
-# ---------------------------------------------------------------------------
-# Health models
-# ---------------------------------------------------------------------------
-
-
-class HookHealthStatus(str, Enum):
-    healthy = "healthy"  # green — reachable, no failures in last 1h
-    degraded = "degraded"  # yellow — reachable, failures in last 1h
-    unreachable = "unreachable"  # red — is_reachable=false or null
-
-
-class HookFailureRecord(BaseModel):
+class HookExecutionRecord(BaseModel):
     error_message: str | None = None
     status_code: int | None = None
     duration_ms: int | None = None
     created_at: datetime
-
-
-class HookHealthResponse(BaseModel):
-    status: HookHealthStatus
-    recent_failures: list[HookFailureRecord] = Field(
-        default_factory=list,
-        description="Last 10 failures, newest first",
-        max_length=10,
-    )

backend/onyx/hooks/points/base.py

@@ -1,6 +1,7 @@
-from abc import ABC
-from abc import abstractmethod
 from typing import Any
+from typing import ClassVar
+
+from pydantic import BaseModel
 
 from onyx.db.enums import HookFailStrategy
 from onyx.db.enums import HookPoint
@@ -13,22 +14,25 @@ _REQUIRED_ATTRS = (
     "default_timeout_seconds",
     "fail_hard_description",
     "default_fail_strategy",
+    "payload_model",
+    "response_model",
 )
 
 
-class HookPointSpec(ABC):
+class HookPointSpec:
     """Static metadata and contract for a pipeline hook point.
 
-    This is NOT a regular class meant for direct instantiation by callers.
     Each concrete subclass represents exactly one hook point and is instantiated
-    once at startup, registered in onyx.hooks.registry._REGISTRY. No caller
-    should ever create instances directly — use get_hook_point_spec() or
-    get_all_specs() from the registry instead.
+    once at startup, registered in onyx.hooks.registry._REGISTRY. Prefer
+    get_hook_point_spec() or get_all_specs() from the registry over direct
+    instantiation.
 
     Each hook point is a concrete subclass of this class. Onyx engineers
     own these definitions — customers never touch this code.
 
     Subclasses must define all attributes as class-level constants.
+    payload_model and response_model must be Pydantic BaseModel subclasses;
+    input_schema and output_schema are derived from them automatically.
     """
 
     hook_point: HookPoint
@@ -39,21 +43,33 @@ class HookPointSpec(ABC):
     default_fail_strategy: HookFailStrategy
     docs_url: str | None = None
 
+    payload_model: ClassVar[type[BaseModel]]
+    response_model: ClassVar[type[BaseModel]]
+
+    # Computed once at class definition time from payload_model / response_model.
+    input_schema: ClassVar[dict[str, Any]]
+    output_schema: ClassVar[dict[str, Any]]
+
     def __init_subclass__(cls, **kwargs: object) -> None:
+        """Enforce that every concrete subclass declares all required class attributes.
+
+        Called automatically by Python whenever a class inherits from HookPointSpec.
+        Abstract subclasses (those still carrying unimplemented abstract methods) are
+        skipped — they are intermediate base classes and may not yet define everything.
+        Only fully concrete subclasses are validated, ensuring a clear TypeError at
+        import time rather than a confusing AttributeError at runtime.
+        """
         super().__init_subclass__(**kwargs)
-        # Skip intermediate abstract subclasses — they may still be partially defined.
-        if getattr(cls, "__abstractmethods__", None):
-            return
         missing = [attr for attr in _REQUIRED_ATTRS if not hasattr(cls, attr)]
         if missing:
             raise TypeError(f"{cls.__name__} must define class attributes: {missing}")
-
-    @property
-    @abstractmethod
-    def input_schema(self) -> dict[str, Any]:
-        """JSON schema describing the request payload sent to the customer's endpoint."""
-
-    @property
-    @abstractmethod
-    def output_schema(self) -> dict[str, Any]:
-        """JSON schema describing the expected response from the customer's endpoint."""
+        for attr in ("payload_model", "response_model"):
+            val = getattr(cls, attr, None)
+            if val is None or not (
+                isinstance(val, type) and issubclass(val, BaseModel)
+            ):
+                raise TypeError(
+                    f"{cls.__name__}.{attr} must be a Pydantic BaseModel subclass, got {val!r}"
+                )
+        cls.input_schema = cls.payload_model.model_json_schema()
+        cls.output_schema = cls.response_model.model_json_schema()

backend/onyx/hooks/points/document_ingestion.py

@@ -1,10 +1,19 @@
-from typing import Any
+from pydantic import BaseModel
 
 from onyx.db.enums import HookFailStrategy
 from onyx.db.enums import HookPoint
 from onyx.hooks.points.base import HookPointSpec
 
 
+# TODO(@Bo-Onyx): define payload and response fields
+class DocumentIngestionPayload(BaseModel):
+    pass
+
+
+class DocumentIngestionResponse(BaseModel):
+    pass
+
+
 class DocumentIngestionSpec(HookPointSpec):
     """Hook point that runs during document ingestion.
 
@@ -18,12 +27,5 @@ class DocumentIngestionSpec(HookPointSpec):
     fail_hard_description = "The document will not be indexed."
     default_fail_strategy = HookFailStrategy.HARD
 
-    @property
-    def input_schema(self) -> dict[str, Any]:
-        # TODO(@Bo-Onyx): define input schema
-        return {"type": "object", "properties": {}}
-
-    @property
-    def output_schema(self) -> dict[str, Any]:
-        # TODO(@Bo-Onyx): define output schema
-        return {"type": "object", "properties": {}}
+    payload_model = DocumentIngestionPayload
+    response_model = DocumentIngestionResponse

backend/onyx/hooks/points/query_processing.py

@@ -1,10 +1,39 @@
-from typing import Any
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
 
 from onyx.db.enums import HookFailStrategy
 from onyx.db.enums import HookPoint
 from onyx.hooks.points.base import HookPointSpec
 
 
+class QueryProcessingPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    query: str = Field(description="The raw query string exactly as the user typed it.")
+    user_email: str | None = Field(
+        description="Email of the user submitting the query, or null if unauthenticated."
+    )
+    chat_session_id: str = Field(
+        description="UUID of the chat session. Always present — the session is guaranteed to exist by the time this hook fires."
+    )
+
+
+class QueryProcessingResponse(BaseModel):
+    # Intentionally permissive — customer endpoints may return extra fields.
+    query: str | None = Field(
+        default=None,
+        description=(
+            "The query to use in the pipeline. "
+            "Null, empty string, or absent = reject the query."
+        ),
+    )
+    rejection_message: str | None = Field(
+        default=None,
+        description="Message shown to the user when the query is rejected. Falls back to a generic message if not provided.",
+    )
+
+
 class QueryProcessingSpec(HookPointSpec):
     """Hook point that runs on every user query before it enters the pipeline.
 
@@ -37,47 +66,5 @@ class QueryProcessingSpec(HookPointSpec):
     )
     default_fail_strategy = HookFailStrategy.HARD
 
-    @property
-    def input_schema(self) -> dict[str, Any]:
-        return {
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "The raw query string exactly as the user typed it.",
-                },
-                "user_email": {
-                    "type": ["string", "null"],
-                    "description": "Email of the user submitting the query, or null if unauthenticated.",
-                },
-                "chat_session_id": {
-                    "type": "string",
-                    "description": "UUID of the chat session. Always present — the session is guaranteed to exist by the time this hook fires.",
-                },
-            },
-            "required": ["query", "user_email", "chat_session_id"],
-            "additionalProperties": False,
-        }
-
-    @property
-    def output_schema(self) -> dict[str, Any]:
-        return {
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": ["string", "null"],
-                    "description": (
-                        "The (optionally modified) query to use. "
-                        "Set to null to reject the query."
-                    ),
-                },
-                "rejection_message": {
-                    "type": ["string", "null"],
-                    "description": (
-                        "Message shown to the user when query is null. "
-                        "Falls back to a generic message if not provided."
-                    ),
-                },
-            },
-            "required": ["query"],
-        }
+    payload_model = QueryProcessingPayload
+    response_model = QueryProcessingResponse

backend/onyx/hooks/utils.py

@@ -0,0 +1,5 @@
+from onyx.configs.app_configs import HOOK_ENABLED
+from shared_configs.configs import MULTI_TENANT
+
+# True only when hooks are available: single-tenant deployment with HOOK_ENABLED=true.
+HOOKS_AVAILABLE: bool = HOOK_ENABLED and not MULTI_TENANT

backend/onyx/main.py

@@ -77,6 +77,7 @@ from onyx.server.features.default_assistant.api import (
 )
 from onyx.server.features.document_set.api import router as document_set_router
 from onyx.server.features.hierarchy.api import router as hierarchy_router
+from onyx.server.features.hooks.api import router as hook_router
 from onyx.server.features.input_prompt.api import (
     admin_router as admin_input_prompt_router,
 )
@@ -453,6 +454,7 @@ def get_application(lifespan_override: Lifespan | None = None) -> FastAPI:
 
     register_onyx_exception_handlers(application)
 
+    include_router_with_global_prefix_prepended(application, hook_router)
     include_router_with_global_prefix_prepended(application, password_router)
     include_router_with_global_prefix_prepended(application, chat_router)
     include_router_with_global_prefix_prepended(application, query_router)

backend/onyx/server/features/hooks/api.py

@@ -0,0 +1,453 @@
+import httpx
+from fastapi import APIRouter
+from fastapi import Depends
+from fastapi import Query
+from sqlalchemy.orm import Session
+
+from onyx.auth.users import current_admin_user
+from onyx.auth.users import User
+from onyx.db.constants import UNSET
+from onyx.db.constants import UnsetType
+from onyx.db.engine.sql_engine import get_session
+from onyx.db.engine.sql_engine import get_session_with_current_tenant
+from onyx.db.hook import create_hook__no_commit
+from onyx.db.hook import delete_hook__no_commit
+from onyx.db.hook import get_hook_by_id
+from onyx.db.hook import get_hook_execution_logs
+from onyx.db.hook import get_hooks
+from onyx.db.hook import update_hook__no_commit
+from onyx.db.models import Hook
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.hooks.api_dependencies import require_hook_enabled
+from onyx.hooks.models import HookCreateRequest
+from onyx.hooks.models import HookExecutionRecord
+from onyx.hooks.models import HookPointMetaResponse
+from onyx.hooks.models import HookResponse
+from onyx.hooks.models import HookUpdateRequest
+from onyx.hooks.models import HookValidateResponse
+from onyx.hooks.models import HookValidateStatus
+from onyx.hooks.registry import get_all_specs
+from onyx.hooks.registry import get_hook_point_spec
+from onyx.utils.logger import setup_logger
+from onyx.utils.url import SSRFException
+from onyx.utils.url import validate_outbound_http_url
+
+logger = setup_logger()
+
+# ---------------------------------------------------------------------------
+# SSRF protection
+# ---------------------------------------------------------------------------
+
+
+def _check_ssrf_safety(endpoint_url: str) -> None:
+    """Raise OnyxError if endpoint_url could be used for SSRF.
+
+    Delegates to validate_outbound_http_url with https_only=True.
+    """
+    try:
+        validate_outbound_http_url(endpoint_url, https_only=True)
+    except (SSRFException, ValueError) as e:
+        raise OnyxError(OnyxErrorCode.INVALID_INPUT, str(e))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _hook_to_response(hook: Hook, creator_email: str | None = None) -> HookResponse:
+    return HookResponse(
+        id=hook.id,
+        name=hook.name,
+        hook_point=hook.hook_point,
+        endpoint_url=hook.endpoint_url,
+        fail_strategy=hook.fail_strategy,
+        timeout_seconds=hook.timeout_seconds,
+        is_active=hook.is_active,
+        is_reachable=hook.is_reachable,
+        creator_email=(
+            creator_email
+            if creator_email is not None
+            else (hook.creator.email if hook.creator else None)
+        ),
+        created_at=hook.created_at,
+        updated_at=hook.updated_at,
+    )
+
+
+def _get_hook_or_404(
+    db_session: Session,
+    hook_id: int,
+    include_creator: bool = False,
+) -> Hook:
+    hook = get_hook_by_id(
+        db_session=db_session,
+        hook_id=hook_id,
+        include_creator=include_creator,
+    )
+    if hook is None:
+        raise OnyxError(OnyxErrorCode.NOT_FOUND, f"Hook {hook_id} not found.")
+    return hook
+
+
+def _raise_for_validation_failure(validation: HookValidateResponse) -> None:
+    """Raise an appropriate OnyxError for a non-passed validation result."""
+    if validation.status == HookValidateStatus.auth_failed:
+        raise OnyxError(OnyxErrorCode.CREDENTIAL_INVALID, validation.error_message)
+    if validation.status == HookValidateStatus.timeout:
+        raise OnyxError(
+            OnyxErrorCode.GATEWAY_TIMEOUT,
+            f"Endpoint validation failed: {validation.error_message}",
+        )
+    raise OnyxError(
+        OnyxErrorCode.BAD_GATEWAY,
+        f"Endpoint validation failed: {validation.error_message}",
+    )
+
+
+def _validate_endpoint(
+    endpoint_url: str,
+    api_key: str | None,
+    timeout_seconds: float,
+) -> HookValidateResponse:
+    """Check whether endpoint_url is reachable by sending an empty POST request.
+
+    We use POST since hook endpoints expect POST requests. The server will typically
+    respond with 4xx (missing/invalid body) — that is fine. Any HTTP response means
+    the server is up and routable. A 401/403 response returns auth_failed
+    (not reachable — indicates the api_key is invalid).
+
+    Timeout handling:
+    - ConnectTimeout: TCP handshake never completed → cannot_connect.
+    - ReadTimeout / WriteTimeout: TCP was established, server responded slowly → timeout
+      (operator should consider increasing timeout_seconds).
+    - All other exceptions → cannot_connect.
+    """
+    _check_ssrf_safety(endpoint_url)
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    try:
+        with httpx.Client(timeout=timeout_seconds, follow_redirects=False) as client:
+            response = client.post(endpoint_url, headers=headers)
+        if response.status_code in (401, 403):
+            return HookValidateResponse(
+                status=HookValidateStatus.auth_failed,
+                error_message=f"Authentication failed (HTTP {response.status_code})",
+            )
+        return HookValidateResponse(status=HookValidateStatus.passed)
+    except httpx.TimeoutException as exc:
+        # ConnectTimeout: TCP handshake never completed → cannot_connect.
+        # ReadTimeout / WriteTimeout: TCP was established, server just responded slowly → timeout.
+        if isinstance(exc, httpx.ConnectTimeout):
+            logger.warning(
+                "Hook endpoint validation: connect timeout for %s",
+                endpoint_url,
+                exc_info=exc,
+            )
+            return HookValidateResponse(
+                status=HookValidateStatus.cannot_connect, error_message=str(exc)
+            )
+        logger.warning(
+            "Hook endpoint validation: read/write timeout for %s",
+            endpoint_url,
+            exc_info=exc,
+        )
+        return HookValidateResponse(
+            status=HookValidateStatus.timeout,
+            error_message="Endpoint timed out — consider increasing timeout_seconds.",
+        )
+    except Exception as exc:
+        logger.warning(
+            "Hook endpoint validation: connection error for %s",
+            endpoint_url,
+            exc_info=exc,
+        )
+        return HookValidateResponse(
+            status=HookValidateStatus.cannot_connect, error_message=str(exc)
+        )
+
+
+# ---------------------------------------------------------------------------
+# Routers
+# ---------------------------------------------------------------------------
+
+router = APIRouter(prefix="/admin/hooks")
+
+
+# ---------------------------------------------------------------------------
+# Hook endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/specs")
+def get_hook_point_specs(
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+) -> list[HookPointMetaResponse]:
+    return [
+        HookPointMetaResponse(
+            hook_point=spec.hook_point,
+            display_name=spec.display_name,
+            description=spec.description,
+            docs_url=spec.docs_url,
+            input_schema=spec.input_schema,
+            output_schema=spec.output_schema,
+            default_timeout_seconds=spec.default_timeout_seconds,
+            default_fail_strategy=spec.default_fail_strategy,
+            fail_hard_description=spec.fail_hard_description,
+        )
+        for spec in get_all_specs()
+    ]
+
+
+@router.get("")
+def list_hooks(
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> list[HookResponse]:
+    hooks = get_hooks(db_session=db_session, include_creator=True)
+    return [_hook_to_response(h) for h in hooks]
+
+
+@router.post("")
+def create_hook(
+    req: HookCreateRequest,
+    user: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookResponse:
+    """Create a new hook. The endpoint is validated before persisting — creation fails if
+    the endpoint cannot be reached or the api_key is invalid. Hooks are created inactive;
+    use POST /{hook_id}/activate once ready to receive traffic."""
+    spec = get_hook_point_spec(req.hook_point)
+    api_key = req.api_key.get_secret_value() if req.api_key else None
+    validation = _validate_endpoint(
+        endpoint_url=req.endpoint_url,
+        api_key=api_key,
+        timeout_seconds=req.timeout_seconds or spec.default_timeout_seconds,
+    )
+    if validation.status != HookValidateStatus.passed:
+        _raise_for_validation_failure(validation)
+
+    hook = create_hook__no_commit(
+        db_session=db_session,
+        name=req.name,
+        hook_point=req.hook_point,
+        endpoint_url=req.endpoint_url,
+        api_key=api_key,
+        fail_strategy=req.fail_strategy or spec.default_fail_strategy,
+        timeout_seconds=req.timeout_seconds or spec.default_timeout_seconds,
+        creator_id=user.id,
+    )
+    hook.is_reachable = True
+    db_session.commit()
+    return _hook_to_response(hook, creator_email=user.email)
+
+
+@router.get("/{hook_id}")
+def get_hook(
+    hook_id: int,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookResponse:
+    hook = _get_hook_or_404(db_session, hook_id, include_creator=True)
+    return _hook_to_response(hook)
+
+
+@router.patch("/{hook_id}")
+def update_hook(
+    hook_id: int,
+    req: HookUpdateRequest,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookResponse:
+    """Update hook fields. If endpoint_url, api_key, or timeout_seconds changes, the
+    endpoint is re-validated using the effective values. For active hooks the update is
+    rejected on validation failure, keeping live traffic unaffected. For inactive hooks
+    the update goes through regardless and is_reachable is updated to reflect the result.
+
+    Note: if an active hook's endpoint is currently down, even a timeout_seconds-only
+    increase will be rejected. The recovery flow is: deactivate → update → reactivate.
+    """
+    # api_key: UNSET = no change, None = clear, value = update
+    api_key: str | None | UnsetType
+    if "api_key" not in req.model_fields_set:
+        api_key = UNSET
+    elif req.api_key is None:
+        api_key = None
+    else:
+        api_key = req.api_key.get_secret_value()
+
+    endpoint_url_changing = "endpoint_url" in req.model_fields_set
+    api_key_changing = not isinstance(api_key, UnsetType)
+    timeout_changing = "timeout_seconds" in req.model_fields_set
+
+    validated_is_reachable: bool | None = None
+    if endpoint_url_changing or api_key_changing or timeout_changing:
+        existing = _get_hook_or_404(db_session, hook_id)
+        effective_url: str = (
+            req.endpoint_url if endpoint_url_changing else existing.endpoint_url  # type: ignore[assignment]  # endpoint_url is required on create and cannot be cleared on update
+        )
+        effective_api_key: str | None = (
+            (api_key if not isinstance(api_key, UnsetType) else None)
+            if api_key_changing
+            else (
+                existing.api_key.get_value(apply_mask=False)
+                if existing.api_key
+                else None
+            )
+        )
+        effective_timeout: float = (
+            req.timeout_seconds if timeout_changing else existing.timeout_seconds  # type: ignore[assignment]  # req.timeout_seconds is non-None when timeout_changing (validated by HookUpdateRequest)
+        )
+        validation = _validate_endpoint(
+            endpoint_url=effective_url,
+            api_key=effective_api_key,
+            timeout_seconds=effective_timeout,
+        )
+        if existing.is_active and validation.status != HookValidateStatus.passed:
+            _raise_for_validation_failure(validation)
+        validated_is_reachable = validation.status == HookValidateStatus.passed
+
+    hook = update_hook__no_commit(
+        db_session=db_session,
+        hook_id=hook_id,
+        name=req.name,
+        endpoint_url=(req.endpoint_url if endpoint_url_changing else UNSET),
+        api_key=api_key,
+        fail_strategy=req.fail_strategy,
+        timeout_seconds=req.timeout_seconds,
+        is_reachable=validated_is_reachable,
+        include_creator=True,
+    )
+    db_session.commit()
+    return _hook_to_response(hook)
+
+
+@router.delete("/{hook_id}")
+def delete_hook(
+    hook_id: int,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> None:
+    delete_hook__no_commit(db_session=db_session, hook_id=hook_id)
+    db_session.commit()
+
+
+@router.post("/{hook_id}/activate")
+def activate_hook(
+    hook_id: int,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookResponse:
+    hook = _get_hook_or_404(db_session, hook_id)
+    if not hook.endpoint_url:
+        raise OnyxError(
+            OnyxErrorCode.INVALID_INPUT, "Hook has no endpoint URL configured."
+        )
+
+    api_key = hook.api_key.get_value(apply_mask=False) if hook.api_key else None
+    validation = _validate_endpoint(
+        endpoint_url=hook.endpoint_url,
+        api_key=api_key,
+        timeout_seconds=hook.timeout_seconds,
+    )
+    if validation.status != HookValidateStatus.passed:
+        # Persist is_reachable=False in a separate session so the request
+        # session has no commits on the failure path and the transaction
+        # boundary stays clean.
+        if hook.is_reachable is not False:
+            with get_session_with_current_tenant() as side_session:
+                update_hook__no_commit(
+                    db_session=side_session, hook_id=hook_id, is_reachable=False
+                )
+                side_session.commit()
+        _raise_for_validation_failure(validation)
+
+    hook = update_hook__no_commit(
+        db_session=db_session,
+        hook_id=hook_id,
+        is_active=True,
+        is_reachable=True,
+        include_creator=True,
+    )
+    db_session.commit()
+    return _hook_to_response(hook)
+
+
+@router.post("/{hook_id}/validate")
+def validate_hook(
+    hook_id: int,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookValidateResponse:
+    hook = _get_hook_or_404(db_session, hook_id)
+    if not hook.endpoint_url:
+        raise OnyxError(
+            OnyxErrorCode.INVALID_INPUT, "Hook has no endpoint URL configured."
+        )
+
+    api_key = hook.api_key.get_value(apply_mask=False) if hook.api_key else None
+    validation = _validate_endpoint(
+        endpoint_url=hook.endpoint_url,
+        api_key=api_key,
+        timeout_seconds=hook.timeout_seconds,
+    )
+    validation_passed = validation.status == HookValidateStatus.passed
+    if hook.is_reachable != validation_passed:
+        update_hook__no_commit(
+            db_session=db_session, hook_id=hook_id, is_reachable=validation_passed
+        )
+        db_session.commit()
+    return validation
+
+
+@router.post("/{hook_id}/deactivate")
+def deactivate_hook(
+    hook_id: int,
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> HookResponse:
+    hook = update_hook__no_commit(
+        db_session=db_session,
+        hook_id=hook_id,
+        is_active=False,
+        include_creator=True,
+    )
+    db_session.commit()
+    return _hook_to_response(hook)
+
+
+# ---------------------------------------------------------------------------
+# Execution log endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/{hook_id}/execution-logs")
+def list_hook_execution_logs(
+    hook_id: int,
+    limit: int = Query(default=10, ge=1, le=100),
+    _: User = Depends(current_admin_user),
+    _hook_enabled: None = Depends(require_hook_enabled),
+    db_session: Session = Depends(get_session),
+) -> list[HookExecutionRecord]:
+    _get_hook_or_404(db_session, hook_id)
+    logs = get_hook_execution_logs(db_session=db_session, hook_id=hook_id, limit=limit)
+    return [
+        HookExecutionRecord(
+            error_message=log.error_message,
+            status_code=log.status_code,
+            duration_ms=log.duration_ms,
+            created_at=log.created_at,
+        )
+        for log in logs
+    ]

backend/onyx/utils/url.py

@@ -140,10 +140,20 @@ def _validate_and_resolve_url(url: str) -> tuple[str, str, int]:
     return validated_ip, hostname, port
 
 
-def validate_outbound_http_url(url: str, *, allow_private_network: bool = False) -> str:
+def validate_outbound_http_url(
+    url: str,
+    *,
+    allow_private_network: bool = False,
+    https_only: bool = False,
+) -> str:
     """
     Validate a URL that will be used by backend outbound HTTP calls.
 
+    Args:
+        url: The URL to validate.
+        allow_private_network: If True, skip private/reserved IP checks.
+        https_only: If True, reject http:// URLs (only https:// is allowed).
+
     Returns:
         A normalized URL string with surrounding whitespace removed.
 
@@ -157,7 +167,12 @@ def validate_outbound_http_url(url: str, *, allow_private_network: bool = False)
 
     parsed = urlparse(normalized_url)
 
-    if parsed.scheme not in ("http", "https"):
+    if https_only:
+        if parsed.scheme != "https":
+            raise SSRFException(
+                f"Invalid URL scheme '{parsed.scheme}'. Only https is allowed."
+            )
+    elif parsed.scheme not in ("http", "https"):
         raise SSRFException(
             f"Invalid URL scheme '{parsed.scheme}'. Only http and https are allowed."
         )

backend/tests/integration/multitenant_tests/migrations/test_run_multitenant_migrations.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import os
 import subprocess
 import sys
+import time
 import uuid
 from collections.abc import Generator
 
@@ -28,6 +29,9 @@ _BACKEND_DIR = os.path.normpath(
     os.path.join(os.path.dirname(__file__), "..", "..", "..", "..")
 )
 
+_DROP_SCHEMA_MAX_RETRIES = 3
+_DROP_SCHEMA_RETRY_DELAY_SEC = 2
+
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -50,6 +54,39 @@ def _run_script(
     )
 
 
+def _force_drop_schema(engine: Engine, schema: str) -> None:
+    """Terminate backends using *schema* then drop it, retrying on deadlock.
+
+    Background Celery workers may discover test schemas (they match the
+    ``tenant_`` prefix) and hold locks on tables inside them.  A bare
+    ``DROP SCHEMA … CASCADE`` can deadlock with those workers, so we
+    first kill their connections and retry if we still hit a deadlock.
+    """
+    for attempt in range(_DROP_SCHEMA_MAX_RETRIES):
+        try:
+            with engine.connect() as conn:
+                conn.execute(
+                    text(
+                        """
+                        SELECT pg_terminate_backend(l.pid)
+                        FROM pg_locks l
+                        JOIN pg_class c ON c.oid = l.relation
+                        JOIN pg_namespace n ON n.oid = c.relnamespace
+                        WHERE n.nspname = :schema
+                          AND l.pid != pg_backend_pid()
+                        """
+                    ),
+                    {"schema": schema},
+                )
+                conn.execute(text(f'DROP SCHEMA IF EXISTS "{schema}" CASCADE'))
+                conn.commit()
+            return
+        except Exception:
+            if attempt == _DROP_SCHEMA_MAX_RETRIES - 1:
+                raise
+            time.sleep(_DROP_SCHEMA_RETRY_DELAY_SEC)
+
+
 # ---------------------------------------------------------------------------
 # Fixtures
 # ---------------------------------------------------------------------------
@@ -104,9 +141,7 @@ def tenant_schema_at_head(
 
     yield schema
 
-    with engine.connect() as conn:
-        conn.execute(text(f'DROP SCHEMA IF EXISTS "{schema}" CASCADE'))
-        conn.commit()
+    _force_drop_schema(engine, schema)
 
 
 @pytest.fixture
@@ -123,9 +158,7 @@ def tenant_schema_empty(engine: Engine) -> Generator[str, None, None]:
 
     yield schema
 
-    with engine.connect() as conn:
-        conn.execute(text(f'DROP SCHEMA IF EXISTS "{schema}" CASCADE'))
-        conn.commit()
+    _force_drop_schema(engine, schema)
 
 
 @pytest.fixture
@@ -150,9 +183,7 @@ def tenant_schema_bad_rev(engine: Engine) -> Generator[str, None, None]:
 
     yield schema
 
-    with engine.connect() as conn:
-        conn.execute(text(f'DROP SCHEMA IF EXISTS "{schema}" CASCADE'))
-        conn.commit()
+    _force_drop_schema(engine, schema)
 
 
 # ---------------------------------------------------------------------------

backend/tests/integration/tests/query_history/test_query_history.py

@@ -1,3 +1,5 @@
+import csv
+import io
 import os
 from datetime import datetime
 from datetime import timedelta
@@ -139,12 +141,12 @@ def test_chat_history_csv_export(
     assert headers["Content-Type"] == "text/csv; charset=utf-8"
     assert "Content-Disposition" in headers
 
-    # Verify CSV content
-    csv_lines = csv_content.strip().split("\n")
-    assert len(csv_lines) == 3  # Header + 2 QA pairs
-    assert "chat_session_id" in csv_content
-    assert "user_message" in csv_content
-    assert "ai_response" in csv_content
+    # Use csv.reader to properly handle newlines inside quoted fields
+    csv_rows = list(csv.reader(io.StringIO(csv_content)))
+    assert len(csv_rows) == 3  # Header + 2 QA pairs
+    assert csv_rows[0][0] == "chat_session_id"
+    assert "user_message" in csv_rows[0]
+    assert "ai_response" in csv_rows[0]
     assert "What was the Q1 revenue?" in csv_content
     assert "What about Q2 revenue?" in csv_content
 
@@ -156,5 +158,5 @@ def test_chat_history_csv_export(
         end_time=past_end,
         user_performing_action=admin_user,
     )
-    csv_lines = csv_content.strip().split("\n")
-    assert len(csv_lines) == 1  # Only header, no data rows
+    csv_rows = list(csv.reader(io.StringIO(csv_content)))
+    assert len(csv_rows) == 1  # Only header, no data rows

backend/tests/unit/onyx/hooks/test_base_spec.py

@@ -1,6 +1,5 @@
-from typing import Any
-
 import pytest
+from pydantic import BaseModel
 
 from onyx.db.enums import HookPoint
 from onyx.hooks.points.base import HookPointSpec
@@ -11,12 +10,10 @@ def test_init_subclass_raises_for_missing_attrs() -> None:
 
         class IncompleteSpec(HookPointSpec):
             hook_point = HookPoint.QUERY_PROCESSING
-            # missing display_name, description, etc.
+            # missing display_name, description, payload_model, response_model, etc.
 
-            @property
-            def input_schema(self) -> dict[str, Any]:
-                return {}
+            class _Payload(BaseModel):
+                pass
 
-            @property
-            def output_schema(self) -> dict[str, Any]:
-                return {}
+            payload_model = _Payload
+            response_model = _Payload

backend/tests/unit/onyx/hooks/test_executor.py

@@ -0,0 +1,541 @@
+"""Unit tests for the hook executor."""
+
+import json
+from typing import Any
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.hooks.executor import execute_hook
+from onyx.hooks.executor import HookSkipped
+from onyx.hooks.executor import HookSoftFailed
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_PAYLOAD: dict[str, Any] = {"query": "test", "user_email": "u@example.com"}
+_RESPONSE_PAYLOAD: dict[str, Any] = {"rewritten_query": "better test"}
+
+
+def _make_hook(
+    *,
+    is_active: bool = True,
+    endpoint_url: str | None = "https://hook.example.com/query",
+    api_key: MagicMock | None = None,
+    timeout_seconds: float = 5.0,
+    fail_strategy: HookFailStrategy = HookFailStrategy.SOFT,
+    hook_id: int = 1,
+    is_reachable: bool | None = None,
+) -> MagicMock:
+    hook = MagicMock()
+    hook.is_active = is_active
+    hook.endpoint_url = endpoint_url
+    hook.api_key = api_key
+    hook.timeout_seconds = timeout_seconds
+    hook.id = hook_id
+    hook.fail_strategy = fail_strategy
+    hook.is_reachable = is_reachable
+    return hook
+
+
+def _make_api_key(value: str) -> MagicMock:
+    api_key = MagicMock()
+    api_key.get_value.return_value = value
+    return api_key
+
+
+def _make_response(
+    *,
+    status_code: int = 200,
+    json_return: Any = _RESPONSE_PAYLOAD,
+    json_side_effect: Exception | None = None,
+) -> MagicMock:
+    """Build a response mock with controllable json() behaviour."""
+    response = MagicMock()
+    response.status_code = status_code
+    if json_side_effect is not None:
+        response.json.side_effect = json_side_effect
+    else:
+        response.json.return_value = json_return
+    return response
+
+
+def _setup_client(
+    mock_client_cls: MagicMock,
+    *,
+    response: MagicMock | None = None,
+    side_effect: Exception | None = None,
+) -> MagicMock:
+    """Wire up the httpx.Client mock and return the inner client.
+
+    If side_effect is an httpx.HTTPStatusError, it is raised from
+    raise_for_status() (matching real httpx behaviour) and post() returns a
+    response mock with the matching status_code set.  All other exceptions are
+    raised directly from post().
+    """
+    mock_client = MagicMock()
+
+    if isinstance(side_effect, httpx.HTTPStatusError):
+        error_response = MagicMock()
+        error_response.status_code = side_effect.response.status_code
+        error_response.raise_for_status.side_effect = side_effect
+        mock_client.post = MagicMock(return_value=error_response)
+    else:
+        mock_client.post = MagicMock(
+            side_effect=side_effect, return_value=response if not side_effect else None
+        )
+
+    mock_client_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
+    mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
+    return mock_client
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def db_session() -> MagicMock:
+    return MagicMock()
+
+
+# ---------------------------------------------------------------------------
+# Early-exit guards (no HTTP call, no DB writes)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "hooks_available,hook",
+    [
+        # HOOKS_AVAILABLE=False exits before the DB lookup — hook is irrelevant.
+        pytest.param(False, None, id="hooks_not_available"),
+        pytest.param(True, None, id="hook_not_found"),
+        pytest.param(True, _make_hook(is_active=False), id="hook_inactive"),
+        pytest.param(True, _make_hook(endpoint_url=None), id="no_endpoint_url"),
+    ],
+)
+def test_early_exit_returns_skipped_with_no_db_writes(
+    db_session: MagicMock,
+    hooks_available: bool,
+    hook: MagicMock | None,
+) -> None:
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", hooks_available),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit") as mock_log,
+    ):
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert isinstance(result, HookSkipped)
+    mock_update.assert_not_called()
+    mock_log.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Successful HTTP call
+# ---------------------------------------------------------------------------
+
+
+def test_success_returns_payload_and_sets_reachable(db_session: MagicMock) -> None:
+    hook = _make_hook()
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit") as mock_log,
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(mock_client_cls, response=_make_response())
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert result == _RESPONSE_PAYLOAD
+    _, update_kwargs = mock_update.call_args
+    assert update_kwargs["is_reachable"] is True
+    mock_log.assert_not_called()
+
+
+def test_success_skips_reachable_write_when_already_true(db_session: MagicMock) -> None:
+    """Deduplication guard: a hook already at is_reachable=True that succeeds
+    must not trigger a DB write."""
+    hook = _make_hook(is_reachable=True)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit"),
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(mock_client_cls, response=_make_response())
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert result == _RESPONSE_PAYLOAD
+    mock_update.assert_not_called()
+
+
+def test_non_dict_json_response_is_a_failure(db_session: MagicMock) -> None:
+    """response.json() returning a non-dict (e.g. list) must be treated as failure.
+    The server responded, so is_reachable is not updated."""
+    hook = _make_hook(fail_strategy=HookFailStrategy.SOFT)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit") as mock_log,
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(
+            mock_client_cls,
+            response=_make_response(json_return=["unexpected", "list"]),
+        )
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert isinstance(result, HookSoftFailed)
+    _, log_kwargs = mock_log.call_args
+    assert log_kwargs["is_success"] is False
+    assert "non-dict" in (log_kwargs["error_message"] or "")
+    mock_update.assert_not_called()
+
+
+def test_json_decode_failure_is_a_failure(db_session: MagicMock) -> None:
+    """response.json() raising must be treated as failure with SOFT strategy.
+    The server responded, so is_reachable is not updated."""
+    hook = _make_hook(fail_strategy=HookFailStrategy.SOFT)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit") as mock_log,
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(
+            mock_client_cls,
+            response=_make_response(
+                json_side_effect=json.JSONDecodeError("not JSON", "", 0)
+            ),
+        )
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert isinstance(result, HookSoftFailed)
+    _, log_kwargs = mock_log.call_args
+    assert log_kwargs["is_success"] is False
+    assert "non-JSON" in (log_kwargs["error_message"] or "")
+    mock_update.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# HTTP failure paths
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "exception,fail_strategy,expected_type,expected_is_reachable",
+    [
+        # NetworkError → is_reachable=False
+        pytest.param(
+            httpx.ConnectError("refused"),
+            HookFailStrategy.SOFT,
+            HookSoftFailed,
+            False,
+            id="connect_error_soft",
+        ),
+        pytest.param(
+            httpx.ConnectError("refused"),
+            HookFailStrategy.HARD,
+            OnyxError,
+            False,
+            id="connect_error_hard",
+        ),
+        # 401/403 → is_reachable=False (api_key revoked)
+        pytest.param(
+            httpx.HTTPStatusError(
+                "401",
+                request=MagicMock(),
+                response=MagicMock(status_code=401, text="Unauthorized"),
+            ),
+            HookFailStrategy.SOFT,
+            HookSoftFailed,
+            False,
+            id="auth_401_soft",
+        ),
+        pytest.param(
+            httpx.HTTPStatusError(
+                "403",
+                request=MagicMock(),
+                response=MagicMock(status_code=403, text="Forbidden"),
+            ),
+            HookFailStrategy.HARD,
+            OnyxError,
+            False,
+            id="auth_403_hard",
+        ),
+        # TimeoutException → no is_reachable write (None)
+        pytest.param(
+            httpx.TimeoutException("timeout"),
+            HookFailStrategy.SOFT,
+            HookSoftFailed,
+            None,
+            id="timeout_soft",
+        ),
+        pytest.param(
+            httpx.TimeoutException("timeout"),
+            HookFailStrategy.HARD,
+            OnyxError,
+            None,
+            id="timeout_hard",
+        ),
+        # Other HTTP errors → no is_reachable write (None)
+        pytest.param(
+            httpx.HTTPStatusError(
+                "500",
+                request=MagicMock(),
+                response=MagicMock(status_code=500, text="error"),
+            ),
+            HookFailStrategy.SOFT,
+            HookSoftFailed,
+            None,
+            id="http_status_error_soft",
+        ),
+        pytest.param(
+            httpx.HTTPStatusError(
+                "500",
+                request=MagicMock(),
+                response=MagicMock(status_code=500, text="error"),
+            ),
+            HookFailStrategy.HARD,
+            OnyxError,
+            None,
+            id="http_status_error_hard",
+        ),
+    ],
+)
+def test_http_failure_paths(
+    db_session: MagicMock,
+    exception: Exception,
+    fail_strategy: HookFailStrategy,
+    expected_type: type,
+    expected_is_reachable: bool | None,
+) -> None:
+    hook = _make_hook(fail_strategy=fail_strategy)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit") as mock_update,
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit"),
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(mock_client_cls, side_effect=exception)
+
+        if expected_type is OnyxError:
+            with pytest.raises(OnyxError) as exc_info:
+                execute_hook(
+                    db_session=db_session,
+                    hook_point=HookPoint.QUERY_PROCESSING,
+                    payload=_PAYLOAD,
+                )
+            assert exc_info.value.error_code is OnyxErrorCode.HOOK_EXECUTION_FAILED
+        else:
+            result = execute_hook(
+                db_session=db_session,
+                hook_point=HookPoint.QUERY_PROCESSING,
+                payload=_PAYLOAD,
+            )
+            assert isinstance(result, expected_type)
+
+    if expected_is_reachable is None:
+        mock_update.assert_not_called()
+    else:
+        mock_update.assert_called_once()
+        _, kwargs = mock_update.call_args
+        assert kwargs["is_reachable"] is expected_is_reachable
+
+
+# ---------------------------------------------------------------------------
+# Authorization header
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "api_key_value,expect_auth_header",
+    [
+        pytest.param("secret-token", True, id="api_key_present"),
+        pytest.param(None, False, id="api_key_absent"),
+    ],
+)
+def test_authorization_header(
+    db_session: MagicMock,
+    api_key_value: str | None,
+    expect_auth_header: bool,
+) -> None:
+    api_key = _make_api_key(api_key_value) if api_key_value else None
+    hook = _make_hook(api_key=api_key)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch("onyx.hooks.executor.update_hook__no_commit"),
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit"),
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        mock_client = _setup_client(mock_client_cls, response=_make_response())
+        execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    _, call_kwargs = mock_client.post.call_args
+    if expect_auth_header:
+        assert call_kwargs["headers"]["Authorization"] == f"Bearer {api_key_value}"
+    else:
+        assert "Authorization" not in call_kwargs["headers"]
+
+
+# ---------------------------------------------------------------------------
+# Persist session failure
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "http_exception,expected_result",
+    [
+        pytest.param(None, _RESPONSE_PAYLOAD, id="success_path"),
+        pytest.param(httpx.ConnectError("refused"), OnyxError, id="hard_fail_path"),
+    ],
+)
+def test_persist_session_failure_is_swallowed(
+    db_session: MagicMock,
+    http_exception: Exception | None,
+    expected_result: Any,
+) -> None:
+    """DB session failure in _persist_result must not mask the real return value or OnyxError."""
+    hook = _make_hook(fail_strategy=HookFailStrategy.HARD)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch(
+            "onyx.hooks.executor.get_session_with_current_tenant",
+            side_effect=RuntimeError("DB unavailable"),
+        ),
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(
+            mock_client_cls,
+            response=_make_response() if not http_exception else None,
+            side_effect=http_exception,
+        )
+
+        if expected_result is OnyxError:
+            with pytest.raises(OnyxError) as exc_info:
+                execute_hook(
+                    db_session=db_session,
+                    hook_point=HookPoint.QUERY_PROCESSING,
+                    payload=_PAYLOAD,
+                )
+            assert exc_info.value.error_code is OnyxErrorCode.HOOK_EXECUTION_FAILED
+        else:
+            result = execute_hook(
+                db_session=db_session,
+                hook_point=HookPoint.QUERY_PROCESSING,
+                payload=_PAYLOAD,
+            )
+            assert result == expected_result
+
+
+def test_is_reachable_failure_does_not_prevent_log(db_session: MagicMock) -> None:
+    """is_reachable update failing (e.g. concurrent hook deletion) must not
+    prevent the execution log from being written.
+
+    Simulates the production failure path: update_hook__no_commit raises
+    OnyxError(NOT_FOUND) as it would if the hook was concurrently deleted
+    between the initial lookup and the reachable update.
+    """
+    hook = _make_hook(fail_strategy=HookFailStrategy.SOFT)
+
+    with (
+        patch("onyx.hooks.executor.HOOKS_AVAILABLE", True),
+        patch(
+            "onyx.hooks.executor.get_non_deleted_hook_by_hook_point",
+            return_value=hook,
+        ),
+        patch("onyx.hooks.executor.get_session_with_current_tenant"),
+        patch(
+            "onyx.hooks.executor.update_hook__no_commit",
+            side_effect=OnyxError(OnyxErrorCode.NOT_FOUND, "hook deleted"),
+        ),
+        patch("onyx.hooks.executor.create_hook_execution_log__no_commit") as mock_log,
+        patch("httpx.Client") as mock_client_cls,
+    ):
+        _setup_client(mock_client_cls, side_effect=httpx.ConnectError("refused"))
+        result = execute_hook(
+            db_session=db_session,
+            hook_point=HookPoint.QUERY_PROCESSING,
+            payload=_PAYLOAD,
+        )
+
+    assert isinstance(result, HookSoftFailed)
+    mock_log.assert_called_once()

backend/tests/unit/onyx/hooks/test_query_processing_spec.py

@@ -37,18 +37,20 @@ def test_input_schema_query_is_string() -> None:
 
 def test_input_schema_user_email_is_nullable() -> None:
     props = QueryProcessingSpec().input_schema["properties"]
-    assert "null" in props["user_email"]["type"]
+    # Pydantic v2 emits anyOf for nullable fields
+    assert any(s.get("type") == "null" for s in props["user_email"]["anyOf"])
 
 
-def test_output_schema_query_is_required() -> None:
+def test_output_schema_query_is_optional() -> None:
+    # query defaults to None (absent = reject); not required in the schema
     schema = QueryProcessingSpec().output_schema
-    assert "query" in schema["required"]
+    assert "query" not in schema.get("required", [])
 
 
 def test_output_schema_query_is_nullable() -> None:
-    # null means "reject the query"
+    # null means "reject the query"; Pydantic v2 emits anyOf for nullable fields
     props = QueryProcessingSpec().output_schema["properties"]
-    assert "null" in props["query"]["type"]
+    assert any(s.get("type") == "null" for s in props["query"]["anyOf"])
 
 
 def test_output_schema_rejection_message_is_optional() -> None:

backend/tests/unit/onyx/server/features/hooks/test_api.py

@@ -0,0 +1,278 @@
+"""Unit tests for onyx.server.features.hooks.api helpers.
+
+Covers:
+- _check_ssrf_safety: scheme enforcement and private-IP blocklist
+- _validate_endpoint: httpx exception → HookValidateStatus mapping
+  ConnectTimeout     → cannot_connect  (TCP handshake never completed)
+  ConnectError       → cannot_connect  (DNS / TLS failure)
+  ReadTimeout et al. → timeout         (TCP connected, server slow)
+  Any other exc      → cannot_connect
+- _raise_for_validation_failure: HookValidateStatus → OnyxError mapping
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.hooks.models import HookValidateResponse
+from onyx.hooks.models import HookValidateStatus
+from onyx.server.features.hooks.api import _check_ssrf_safety
+from onyx.server.features.hooks.api import _raise_for_validation_failure
+from onyx.server.features.hooks.api import _validate_endpoint
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_URL = "https://example.com/hook"
+_API_KEY = "secret"
+_TIMEOUT = 5.0
+
+
+def _mock_response(status_code: int) -> MagicMock:
+    response = MagicMock()
+    response.status_code = status_code
+    return response
+
+
+# ---------------------------------------------------------------------------
+# _check_ssrf_safety
+# ---------------------------------------------------------------------------
+
+
+class TestCheckSsrfSafety:
+    def _call(self, url: str) -> None:
+        _check_ssrf_safety(url)
+
+    # --- scheme checks ---
+
+    def test_https_is_allowed(self) -> None:
+        with patch("onyx.utils.url.socket.getaddrinfo") as mock_dns:
+            mock_dns.return_value = [(None, None, None, None, ("93.184.216.34", 0))]
+            self._call("https://example.com/hook")  # must not raise
+
+    @pytest.mark.parametrize(
+        "url", ["http://example.com/hook", "ftp://example.com/hook"]
+    )
+    def test_non_https_scheme_rejected(self, url: str) -> None:
+        with pytest.raises(OnyxError) as exc_info:
+            self._call(url)
+        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+        assert "https" in (exc_info.value.detail or "").lower()
+
+    # --- private IP blocklist ---
+
+    @pytest.mark.parametrize(
+        "ip",
+        [
+            pytest.param("127.0.0.1", id="loopback"),
+            pytest.param("10.0.0.1", id="RFC1918-A"),
+            pytest.param("172.16.0.1", id="RFC1918-B"),
+            pytest.param("192.168.1.1", id="RFC1918-C"),
+            pytest.param("169.254.169.254", id="link-local-IMDS"),
+            pytest.param("100.64.0.1", id="shared-address-space"),
+            pytest.param("::1", id="IPv6-loopback"),
+            pytest.param("fc00::1", id="IPv6-ULA"),
+            pytest.param("fe80::1", id="IPv6-link-local"),
+        ],
+    )
+    def test_private_ip_is_blocked(self, ip: str) -> None:
+        with (
+            patch("onyx.utils.url.socket.getaddrinfo") as mock_dns,
+            pytest.raises(OnyxError) as exc_info,
+        ):
+            mock_dns.return_value = [(None, None, None, None, (ip, 0))]
+            self._call("https://internal.example.com/hook")
+        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+        assert ip in (exc_info.value.detail or "")
+
+    def test_public_ip_is_allowed(self) -> None:
+        with patch("onyx.utils.url.socket.getaddrinfo") as mock_dns:
+            mock_dns.return_value = [(None, None, None, None, ("93.184.216.34", 0))]
+            self._call("https://example.com/hook")  # must not raise
+
+    def test_dns_resolution_failure_raises(self) -> None:
+        import socket
+
+        with (
+            patch(
+                "onyx.utils.url.socket.getaddrinfo",
+                side_effect=socket.gaierror("name not found"),
+            ),
+            pytest.raises(OnyxError) as exc_info,
+        ):
+            self._call("https://no-such-host.example.com/hook")
+        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+
+
+# ---------------------------------------------------------------------------
+# _validate_endpoint
+# ---------------------------------------------------------------------------
+
+
+class TestValidateEndpoint:
+    def _call(self, *, api_key: str | None = _API_KEY) -> HookValidateResponse:
+        # Bypass SSRF check — tested separately in TestCheckSsrfSafety.
+        with patch("onyx.server.features.hooks.api._check_ssrf_safety"):
+            return _validate_endpoint(
+                endpoint_url=_URL,
+                api_key=api_key,
+                timeout_seconds=_TIMEOUT,
+            )
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_2xx_returns_passed(self, mock_client_cls: MagicMock) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.return_value = (
+            _mock_response(200)
+        )
+        assert self._call().status == HookValidateStatus.passed
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_5xx_returns_passed(self, mock_client_cls: MagicMock) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.return_value = (
+            _mock_response(500)
+        )
+        assert self._call().status == HookValidateStatus.passed
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    @pytest.mark.parametrize("status_code", [401, 403])
+    def test_401_403_returns_auth_failed(
+        self, mock_client_cls: MagicMock, status_code: int
+    ) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.return_value = (
+            _mock_response(status_code)
+        )
+        result = self._call()
+        assert result.status == HookValidateStatus.auth_failed
+        assert str(status_code) in (result.error_message or "")
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_4xx_non_auth_returns_passed(self, mock_client_cls: MagicMock) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.return_value = (
+            _mock_response(422)
+        )
+        assert self._call().status == HookValidateStatus.passed
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_connect_timeout_returns_cannot_connect(
+        self, mock_client_cls: MagicMock
+    ) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.side_effect = (
+            httpx.ConnectTimeout("timed out")
+        )
+        assert self._call().status == HookValidateStatus.cannot_connect
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    @pytest.mark.parametrize(
+        "exc",
+        [
+            httpx.ReadTimeout("read timeout"),
+            httpx.WriteTimeout("write timeout"),
+            httpx.PoolTimeout("pool timeout"),
+        ],
+    )
+    def test_read_write_pool_timeout_returns_timeout(
+        self, mock_client_cls: MagicMock, exc: httpx.TimeoutException
+    ) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.side_effect = exc
+        assert self._call().status == HookValidateStatus.timeout
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_connect_error_returns_cannot_connect(
+        self, mock_client_cls: MagicMock
+    ) -> None:
+        # Covers DNS failures, TLS errors, and other connection-level errors.
+        mock_client_cls.return_value.__enter__.return_value.post.side_effect = (
+            httpx.ConnectError("name resolution failed")
+        )
+        assert self._call().status == HookValidateStatus.cannot_connect
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_arbitrary_exception_returns_cannot_connect(
+        self, mock_client_cls: MagicMock
+    ) -> None:
+        mock_client_cls.return_value.__enter__.return_value.post.side_effect = (
+            ConnectionRefusedError("refused")
+        )
+        assert self._call().status == HookValidateStatus.cannot_connect
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_api_key_sent_as_bearer(self, mock_client_cls: MagicMock) -> None:
+        mock_post = mock_client_cls.return_value.__enter__.return_value.post
+        mock_post.return_value = _mock_response(200)
+        self._call(api_key="mykey")
+        _, kwargs = mock_post.call_args
+        assert kwargs["headers"]["Authorization"] == "Bearer mykey"
+
+    @patch("onyx.server.features.hooks.api.httpx.Client")
+    def test_no_api_key_omits_auth_header(self, mock_client_cls: MagicMock) -> None:
+        mock_post = mock_client_cls.return_value.__enter__.return_value.post
+        mock_post.return_value = _mock_response(200)
+        self._call(api_key=None)
+        _, kwargs = mock_post.call_args
+        assert "Authorization" not in kwargs["headers"]
+
+
+# ---------------------------------------------------------------------------
+# _raise_for_validation_failure
+# ---------------------------------------------------------------------------
+
+
+class TestRaiseForValidationFailure:
+    @pytest.mark.parametrize(
+        "status, expected_code",
+        [
+            (HookValidateStatus.auth_failed, OnyxErrorCode.CREDENTIAL_INVALID),
+            (HookValidateStatus.timeout, OnyxErrorCode.GATEWAY_TIMEOUT),
+            (HookValidateStatus.cannot_connect, OnyxErrorCode.BAD_GATEWAY),
+        ],
+    )
+    def test_raises_correct_error_code(
+        self, status: HookValidateStatus, expected_code: OnyxErrorCode
+    ) -> None:
+        validation = HookValidateResponse(status=status, error_message="some error")
+        with pytest.raises(OnyxError) as exc_info:
+            _raise_for_validation_failure(validation)
+        assert exc_info.value.error_code == expected_code
+
+    def test_auth_failed_passes_error_message_directly(self) -> None:
+        validation = HookValidateResponse(
+            status=HookValidateStatus.auth_failed, error_message="bad credentials"
+        )
+        with pytest.raises(OnyxError) as exc_info:
+            _raise_for_validation_failure(validation)
+        assert exc_info.value.detail == "bad credentials"
+
+    @pytest.mark.parametrize(
+        "status", [HookValidateStatus.timeout, HookValidateStatus.cannot_connect]
+    )
+    def test_timeout_and_cannot_connect_wrap_error_message(
+        self, status: HookValidateStatus
+    ) -> None:
+        validation = HookValidateResponse(status=status, error_message="raw error")
+        with pytest.raises(OnyxError) as exc_info:
+            _raise_for_validation_failure(validation)
+        assert exc_info.value.detail == "Endpoint validation failed: raw error"
+
+
+# ---------------------------------------------------------------------------
+# HookValidateStatus enum string values (API contract)
+# ---------------------------------------------------------------------------
+
+
+class TestHookValidateStatusValues:
+    @pytest.mark.parametrize(
+        "status, expected",
+        [
+            (HookValidateStatus.passed, "passed"),
+            (HookValidateStatus.auth_failed, "auth_failed"),
+            (HookValidateStatus.timeout, "timeout"),
+            (HookValidateStatus.cannot_connect, "cannot_connect"),
+        ],
+    )
+    def test_string_values(self, status: HookValidateStatus, expected: str) -> None:
+        assert status == expected

deployment/docker_compose/docker-compose.multitenant-dev.yml

@@ -489,20 +489,18 @@ services:
       - "${HOST_PORT_80:-80}:80"
       - "${HOST_PORT:-3000}:80" # allow for localhost:3000 usage, since that is the norm
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      - ../data/nginx:/nginx-templates:ro
     logging:
       driver: json-file
       options:
         max-size: "50m"
         max-file: "6"
-    # The specified script waits for the api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template"
 
   minio:
     image: minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1

deployment/docker_compose/docker-compose.prod-cloud.yml

@@ -290,25 +290,20 @@ services:
       - "80:80"
       - "443:443"
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      - ../data/nginx:/nginx-templates:ro
       - ../data/certbot/conf:/etc/letsencrypt
       - ../data/certbot/www:/var/www/certbot
-    # sleep a little bit to allow the web_server / api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
     logging:
       driver: json-file
       options:
         max-size: "50m"
         max-file: "6"
-    # The specified script waits for the api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template.prod"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template.prod"
     env_file:
       - .env.nginx
     environment:

deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml

@@ -314,21 +314,19 @@ services:
       - "80:80"
       - "443:443"
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      - ../data/nginx:/nginx-templates:ro
       - ../data/sslcerts:/etc/nginx/sslcerts
     logging:
       driver: json-file
       options:
         max-size: "50m"
         max-file: "6"
-    # The specified script waits for the api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template.prod.no-letsencrypt"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template.prod.no-letsencrypt"
     env_file:
       - .env.nginx
     environment:

deployment/docker_compose/docker-compose.prod.yml

@@ -333,25 +333,20 @@ services:
       - "80:80"
       - "443:443"
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      - ../data/nginx:/nginx-templates:ro
       - ../data/certbot/conf:/etc/letsencrypt
       - ../data/certbot/www:/var/www/certbot
-    # sleep a little bit to allow the web_server / api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
     logging:
       driver: json-file
       options:
         max-size: "50m"
         max-file: "6"
-    # The specified script waits for the api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template.prod"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template.prod"
     env_file:
       - .env.nginx
     environment:

deployment/docker_compose/docker-compose.search-testing.yml

@@ -202,20 +202,18 @@ services:
     ports:
       - "${NGINX_PORT:-3000}:80" # allow for localhost:3000 usage, since that is the norm
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      - ../data/nginx:/nginx-templates:ro
     logging:
       driver: json-file
       options:
         max-size: "50m"
         max-file: "6"
-    # The specified script waits for the api_server to start up.
-    # Without this we've seen issues where nginx shows no error logs but
-    # does not recieve any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template"
 
   minio:
     image: minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1

deployment/docker_compose/docker-compose.yml

@@ -477,7 +477,10 @@ services:
       - "${HOST_PORT_80:-80}:80"
       - "${HOST_PORT:-3000}:80" # allow for localhost:3000 usage, since that is the norm
     volumes:
-      - ../data/nginx:/etc/nginx/conf.d
+      # Mount templates read-only; the startup command copies them into
+      # the writable /etc/nginx/conf.d/ inside the container.  This avoids
+      # "Permission denied" errors on Windows Docker bind mounts.
+      - ../data/nginx:/nginx-templates:ro
     # PRODUCTION: Add SSL certificate volumes for HTTPS support:
     #   - ../data/certbot/conf:/etc/letsencrypt
     #   - ../data/certbot/www:/var/www/certbot
@@ -489,12 +492,13 @@ services:
     # The specified script waits for the api_server to start up.
     # Without this we've seen issues where nginx shows no error logs but
     # does not receive any traffic
-    # NOTE: we have to use dos2unix to remove Carriage Return chars from the file
-    # in order to make this work on both Unix-like systems and windows
     # PRODUCTION: Change to app.conf.template.prod for production nginx config
     command: >
-      /bin/sh -c "dos2unix /etc/nginx/conf.d/run-nginx.sh
-      && /etc/nginx/conf.d/run-nginx.sh app.conf.template"
+      /bin/sh -c "rm -f /etc/nginx/conf.d/default.conf
+      && cp -a /nginx-templates/. /etc/nginx/conf.d/
+      && sed 's/\r$//' /etc/nginx/conf.d/run-nginx.sh > /tmp/run-nginx.sh
+      && chmod +x /tmp/run-nginx.sh
+      && /tmp/run-nginx.sh app.conf.template"
 
   cache:
     image: redis:7.4-alpine

deployment/docker_compose/install.ps1

@@ -2,7 +2,7 @@
 # Usage: .\install.ps1 [OPTIONS]
 # Remote (with params):
 #   & ([scriptblock]::Create((irm https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.ps1))) -Lite -NoPrompt
-# Remote (defaults only):
+# Remote (defaults only, configure via interaction during script):
 #   irm https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.ps1 | iex
 
 param(
@@ -57,11 +57,7 @@ function Print-Step {
 }
 
 function Test-Interactive {
-    if ($NoPrompt) { return $false }
-    try {
-        if ([Console]::IsInputRedirected) { return $false }
-        return $true
-    } catch { return [Environment]::UserInteractive }
+    return -not $NoPrompt
 }
 
 function Prompt-OrDefault {
@@ -89,12 +85,12 @@ function Prompt-VersionTag {
         Write-Host "  - Type a specific tag (e.g., craft-v1.0.0)"
         $version = Prompt-OrDefault "Enter tag [default: craft-latest]" "craft-latest"
     } else {
-        Write-Host "  - Press Enter for latest (recommended)"
+        Write-Host "  - Press Enter for edge (recommended)"
         Write-Host "  - Type a specific tag (e.g., v0.1.0)"
-        $version = Prompt-OrDefault "Enter tag [default: latest]" "latest"
+        $version = Prompt-OrDefault "Enter tag [default: edge]" "edge"
     }
     if     ($script:IncludeCraftMode -and $version -eq "craft-latest") { Print-Info "Selected: craft-latest (Craft enabled)" }
-    elseif ($version -eq "latest") { Print-Info "Selected: Latest tag" }
+    elseif ($version -eq "edge") { Print-Info "Selected: edge (latest nightly)" }
     else   { Print-Info "Selected: $version" }
     return $version
 }
@@ -103,16 +99,16 @@ function Prompt-DeploymentMode {
     param([string]$LiteOverlayPath)
     if ($script:LiteMode) { Print-Info "Deployment mode: Lite (set via -Lite flag)"; return }
     Print-Info "Which deployment mode would you like?"
-    Write-Host "  1) Standard  - Full deployment with search, connectors, and RAG"
-    Write-Host "  2) Lite      - Minimal deployment (no Vespa, Redis, or model servers)"
+    Write-Host "  1) Lite      - Minimal deployment (no Vespa, Redis, or model servers)"
     Write-Host "                  LLM chat, tools, file uploads, and Projects still work"
+    Write-Host "  2) Standard  - Full deployment with search, connectors, and RAG"
     $modeChoice = Prompt-OrDefault "Choose a mode (1 or 2) [default: 1]" "1"
     if ($modeChoice -eq "2") {
+        Print-Info "Selected: Standard mode"
+    } else {
         $script:LiteMode = $true
         Print-Info "Selected: Lite mode"
         if (-not (Ensure-OnyxFile $LiteOverlayPath "$($script:GitHubRawUrl)/$($script:LiteComposeFile)" $script:LiteComposeFile)) { exit 1 }
-    } else {
-        Print-Info "Selected: Standard mode"
     }
 }
 
@@ -358,7 +354,8 @@ function Invoke-OnyxShutdown {
         return
     }
     if (-not (Initialize-ComposeCommand)) { Print-OnyxError "Docker Compose not found."; exit 1 }
-    $result = Invoke-Compose -AutoDetect stop
+    $stopArgs = @("stop")
+    $result = Invoke-Compose -AutoDetect @stopArgs
     if ($result -ne 0) { Print-OnyxError "Failed to stop containers"; exit 1 }
     Print-Success "Onyx containers stopped (paused)"
 }
@@ -367,7 +364,7 @@ function Invoke-OnyxDeleteData {
     Write-Host "`n=== WARNING: This will permanently delete all Onyx data ===`n" -ForegroundColor Red
     Print-Warning "This action will remove all Onyx containers, volumes, files, and user data."
     if (Test-Interactive) {
-        $confirm = Read-Host "Type 'DELETE' to confirm"
+        $confirm = Prompt-OrDefault "Type 'DELETE' to confirm" ""
         if ($confirm -ne "DELETE") { Print-Info "Operation cancelled."; return }
     } else {
         Print-OnyxError "Cannot confirm destructive operation in non-interactive mode."
@@ -375,7 +372,8 @@ function Invoke-OnyxDeleteData {
     }
     $deployDir = Join-Path $script:InstallRoot "deployment"
     if ((Test-Path (Join-Path $deployDir "docker-compose.yml")) -and (Initialize-ComposeCommand)) {
-        $result = Invoke-Compose -AutoDetect down -v
+        $downArgs = @("down", "-v")
+        $result = Invoke-Compose -AutoDetect @downArgs
         if ($result -eq 0) { Print-Success "Containers and volumes removed" }
         else { Print-OnyxError "Failed to remove containers" }
     }
@@ -808,7 +806,7 @@ function Main {
 
     if (Test-Interactive) {
         Write-Host "`nPlease acknowledge and press Enter to continue..." -ForegroundColor Yellow
-        Read-Host | Out-Null
+        $null = Prompt-OrDefault "" ""
     } else {
         Write-Host "`nRunning in non-interactive mode - proceeding automatically..." -ForegroundColor Yellow
     }
@@ -934,15 +932,6 @@ function Main {
     $liteOverlayPath = Join-Path $deploymentDir $script:LiteComposeFile
     if ($script:LiteMode) {
         if (-not (Ensure-OnyxFile $liteOverlayPath "$($script:GitHubRawUrl)/$($script:LiteComposeFile)" $script:LiteComposeFile)) { exit 1 }
-    } elseif (Test-Path $liteOverlayPath) {
-        if (Test-Path (Join-Path $deploymentDir ".env")) {
-            Print-Warning "Existing lite overlay found but -Lite was not passed."
-            $reply = Prompt-OrDefault "Remove lite overlay and switch to standard mode? (y/N)" "n"
-            if ($reply -match '^[Yy]') { Remove-Item -Force $liteOverlayPath; Print-Info "Switched to standard mode" }
-            else { $script:LiteMode = $true; Print-Info "Keeping lite mode" }
-        } else {
-            Remove-Item -Force $liteOverlayPath
-        }
     }
 
     $envTemplateDest = Join-Path $deploymentDir "env.template"
@@ -962,7 +951,8 @@ function Main {
     # Check if services are already running
     if ((Test-Path $composeDest) -and (Initialize-ComposeCommand)) {
         $running = @()
-        try { $running = @(Invoke-Compose -AutoDetect ps -q 2>$null | Where-Object { $_ }) } catch { }
+        $psArgs = @("ps", "-q")
+        try { $running = @(Invoke-Compose -AutoDetect @psArgs 2>$null | Where-Object { $_ }) } catch { }
         if ($running.Count -gt 0) {
             Print-OnyxError "Onyx services are currently running!"
             Print-Info "Run '.\install.ps1 -Shutdown' first, then re-run this script."
@@ -1028,6 +1018,12 @@ function Main {
         Print-Info "You can customize .env later for OAuth/SAML, AI models, domain settings, and Craft."
     }
 
+    # Clean up stale lite overlay if standard mode was selected
+    if (-not $script:LiteMode -and (Test-Path $liteOverlayPath)) {
+        Remove-Item -Force $liteOverlayPath
+        Print-Info "Removed previous lite overlay (switching to standard mode)"
+    }
+
     # ── Step 6: Check Ports ───────────────────────────────────────────────
     Print-Step "Checking for available ports"
     $availablePort = Find-AvailablePort 3000
@@ -1037,7 +1033,7 @@ function Main {
     Print-Success "Using port $availablePort for nginx"
 
     $currentImageTag = Get-EnvFileValue -Path $envFile -Key "IMAGE_TAG"
-    $useLatest = ($currentImageTag -eq "latest" -or $currentImageTag -match '^craft-')
+    $useLatest = ($currentImageTag -eq "edge" -or $currentImageTag -eq "latest" -or $currentImageTag -match '^craft-')
     if ($useLatest) { Print-Info "Using '$currentImageTag' tag - will force pull and recreate containers" }
 
     # For pinned version tags, re-download config files from that tag so the
@@ -1069,8 +1065,9 @@ function Main {
     # ── Step 8: Start Services ────────────────────────────────────────────
     Print-Step "Starting Onyx services"
     Print-Info "Launching containers..."
-    if ($useLatest) { $upResult = Invoke-Compose up -d --pull always --force-recreate }
-    else { $upResult = Invoke-Compose up -d }
+    $upArgs = @("up", "-d")
+    if ($useLatest) { $upArgs += @("--pull", "always", "--force-recreate") }
+    $upResult = Invoke-Compose @upArgs
     if ($upResult -ne 0) { Print-OnyxError "Failed to start Onyx services"; exit 1 }
 
     # ── Step 9: Container Health ──────────────────────────────────────────
@@ -1078,7 +1075,8 @@ function Main {
     Start-Sleep -Seconds 10
     $restartIssues = $false
     $containerIds = @()
-    try { $containerIds = @(Invoke-Compose ps -q 2>$null | Where-Object { $_ }) } catch { }
+    $psArgs = @("ps", "-q")
+    try { $containerIds = @(Invoke-Compose @psArgs 2>$null | Where-Object { $_ }) } catch { }
 
     foreach ($cid in $containerIds) {
         if ([string]::IsNullOrWhiteSpace($cid)) { continue }

deployment/docker_compose/install.sh

@@ -96,8 +96,8 @@ fi
 
 # When --lite is passed as a flag, lower resource thresholds early (before the
 # resource check). When lite is chosen interactively, the thresholds are adjusted
-# inside the new-deployment flow, after the resource check has already passed
-# with the standard thresholds — which is the safer direction.
+# after the resource check has already passed with the standard thresholds —
+# which is the safer direction.
 if [[ "$LITE_MODE" = true ]]; then
     EXPECTED_DOCKER_RAM_GB=4
     EXPECTED_DISK_GB=16
@@ -110,9 +110,6 @@ LITE_COMPOSE_FILE="docker-compose.onyx-lite.yml"
 # Build the -f flags for docker compose.
 # Pass "true" as $1 to auto-detect a previously-downloaded lite overlay
 # (used by shutdown/delete-data so users don't need to remember --lite).
-# Without the argument, the lite overlay is only included when --lite was
-# explicitly passed — preventing install/start from silently staying in
-# lite mode just because the file exists on disk from a prior run.
 compose_file_args() {
     local auto_detect="${1:-false}"
     local args="-f docker-compose.yml"
@@ -177,34 +174,42 @@ ensure_file() {
 
 # --- Interactive prompt helpers ---
 is_interactive() {
-    [[ "$NO_PROMPT" = false ]] && [[ -t 0 ]]
+    [[ "$NO_PROMPT" = false ]] && [[ -r /dev/tty ]] && [[ -w /dev/tty ]]
+}
+
+read_prompt_line() {
+    local prompt_text="$1"
+    if ! is_interactive; then
+        REPLY=""
+        return
+    fi
+    [[ -n "$prompt_text" ]] && printf "%s" "$prompt_text" > /dev/tty
+    IFS= read -r REPLY < /dev/tty || REPLY=""
+}
+
+read_prompt_char() {
+    local prompt_text="$1"
+    if ! is_interactive; then
+        REPLY=""
+        return
+    fi
+    [[ -n "$prompt_text" ]] && printf "%s" "$prompt_text" > /dev/tty
+    IFS= read -r -n 1 REPLY < /dev/tty || REPLY=""
+    printf "\n" > /dev/tty
 }
 
 prompt_or_default() {
     local prompt_text="$1"
     local default_value="$2"
-    if is_interactive; then
-        read -p "$prompt_text" -r REPLY
-        if [[ -z "$REPLY" ]]; then
-            REPLY="$default_value"
-        fi
-    else
-        REPLY="$default_value"
-    fi
+    read_prompt_line "$prompt_text"
+    [[ -z "$REPLY" ]] && REPLY="$default_value"
 }
 
 prompt_yn_or_default() {
     local prompt_text="$1"
     local default_value="$2"
-    if is_interactive; then
-        read -p "$prompt_text" -n 1 -r
-        echo ""
-        if [[ -z "$REPLY" ]]; then
-            REPLY="$default_value"
-        fi
-    else
-        REPLY="$default_value"
-    fi
+    read_prompt_char "$prompt_text"
+    [[ -z "$REPLY" ]] && REPLY="$default_value"
 }
 
 confirm_action() {
@@ -305,8 +310,8 @@ if [ "$DELETE_DATA_MODE" = true ]; then
     echo "  • All user data and documents"
     echo ""
     if is_interactive; then
-        read -p "Are you sure you want to continue? Type 'DELETE' to confirm: " -r
-        echo ""
+        prompt_or_default "Are you sure you want to continue? Type 'DELETE' to confirm: " ""
+        echo "" > /dev/tty
         if [ "$REPLY" != "DELETE" ]; then
             print_info "Operation cancelled."
             exit 0
@@ -500,7 +505,7 @@ echo ""
 
 if is_interactive; then
     echo -e "${YELLOW}${BOLD}Please acknowledge and press Enter to continue...${NC}"
-    read -r
+    read_prompt_line ""
     echo ""
 else
     echo -e "${YELLOW}${BOLD}Running in non-interactive mode - proceeding automatically...${NC}"
@@ -745,25 +750,48 @@ if [ "$COMPOSE_VERSION" != "dev" ] && version_compare "$COMPOSE_VERSION" "2.24.0
     print_info "Proceeding with installation despite Docker Compose version compatibility issues..."
 fi
 
-# Handle lite overlay: ensure it if --lite, clean up stale copies otherwise
+# Ask for deployment mode (standard vs lite) unless already set via --lite flag
+if [[ "$LITE_MODE" = false ]]; then
+    print_info "Which deployment mode would you like?"
+    echo ""
+    echo "  1) Lite      - Minimal deployment (no Vespa, Redis, or model servers)"
+    echo "                  LLM chat, tools, file uploads, and Projects still work"
+    echo "  2) Standard  - Full deployment with search, connectors, and RAG"
+    echo ""
+    prompt_or_default "Choose a mode (1 or 2) [default: 1]: " "1"
+    echo ""
+
+    case "$REPLY" in
+        2)
+            print_info "Selected: Standard mode"
+            ;;
+        *)
+            LITE_MODE=true
+            print_info "Selected: Lite mode"
+            ;;
+    esac
+else
+    print_info "Deployment mode: Lite (set via --lite flag)"
+fi
+
+if [[ "$LITE_MODE" = true ]] && [[ "$INCLUDE_CRAFT" = true ]]; then
+    print_error "--include-craft cannot be used with Lite mode."
+    print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+    exit 1
+fi
+
+if [[ "$LITE_MODE" = true ]]; then
+    EXPECTED_DOCKER_RAM_GB=4
+    EXPECTED_DISK_GB=16
+fi
+
+# Handle lite overlay file based on selected mode
 if [[ "$LITE_MODE" = true ]]; then
     ensure_file "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" \
         "${GITHUB_RAW_URL}/${LITE_COMPOSE_FILE}" "${LITE_COMPOSE_FILE}" || exit 1
 elif [[ -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" ]]; then
-    if [[ -f "${INSTALL_ROOT}/deployment/.env" ]]; then
-        print_warning "Existing lite overlay found but --lite was not passed."
-        prompt_yn_or_default "Remove lite overlay and switch to standard mode? (y/N): " "n"
-        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-            print_info "Keeping existing lite overlay. Pass --lite to keep using lite mode."
-            LITE_MODE=true
-        else
-            rm -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}"
-            print_info "Removed lite overlay (switching to standard mode)"
-        fi
-    else
-        rm -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}"
-        print_info "Removed previous lite overlay (switching to standard mode)"
-    fi
+    rm -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}"
+    print_info "Removed previous lite overlay (switching to standard mode)"
 fi
 
 ensure_file "${INSTALL_ROOT}/deployment/env.template" \
@@ -826,22 +854,22 @@ if [ -f "$ENV_FILE" ]; then
     if [ "$REPLY" = "update" ]; then
         print_info "Update selected. Which tag would you like to deploy?"
         echo ""
-        echo "• Press Enter for latest (recommended)"
+        echo "• Press Enter for edge (recommended)"
         echo "• Type a specific tag (e.g., v0.1.0)"
         echo ""
         if [ "$INCLUDE_CRAFT" = true ]; then
             prompt_or_default "Enter tag [default: craft-latest]: " "craft-latest"
             VERSION="$REPLY"
         else
-            prompt_or_default "Enter tag [default: latest]: " "latest"
+            prompt_or_default "Enter tag [default: edge]: " "edge"
             VERSION="$REPLY"
         fi
         echo ""
 
         if [ "$INCLUDE_CRAFT" = true ] && [ "$VERSION" = "craft-latest" ]; then
             print_info "Selected: craft-latest (Craft enabled)"
-        elif [ "$VERSION" = "latest" ]; then
-            print_info "Selected: Latest version"
+        elif [ "$VERSION" = "edge" ]; then
+            print_info "Selected: edge (latest nightly)"
         else
             print_info "Selected: $VERSION"
         fi
@@ -893,45 +921,6 @@ else
     print_info "No existing .env file found. Setting up new deployment..."
     echo ""
 
-    # Ask for deployment mode (standard vs lite) unless already set via --lite flag
-    if [[ "$LITE_MODE" = false ]]; then
-        print_info "Which deployment mode would you like?"
-        echo ""
-        echo "  1) Standard  - Full deployment with search, connectors, and RAG"
-        echo "  2) Lite      - Minimal deployment (no Vespa, Redis, or model servers)"
-        echo "                  LLM chat, tools, file uploads, and Projects still work"
-        echo ""
-        prompt_or_default "Choose a mode (1 or 2) [default: 1]: " "1"
-        echo ""
-
-        case "$REPLY" in
-            2)
-                LITE_MODE=true
-                print_info "Selected: Lite mode"
-                ensure_file "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" \
-                    "${GITHUB_RAW_URL}/${LITE_COMPOSE_FILE}" "${LITE_COMPOSE_FILE}" || exit 1
-                ;;
-            *)
-                print_info "Selected: Standard mode"
-                ;;
-        esac
-    else
-        print_info "Deployment mode: Lite (set via --lite flag)"
-    fi
-
-    # Validate lite + craft combination (could now be set interactively)
-    if [[ "$LITE_MODE" = true ]] && [[ "$INCLUDE_CRAFT" = true ]]; then
-        print_error "--include-craft cannot be used with Lite mode."
-        print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
-        exit 1
-    fi
-
-    # Adjust resource expectations for lite mode
-    if [[ "$LITE_MODE" = true ]]; then
-        EXPECTED_DOCKER_RAM_GB=4
-        EXPECTED_DISK_GB=16
-    fi
-
     # Ask for version
     print_info "Which tag would you like to deploy?"
     echo ""
@@ -942,18 +931,18 @@ else
         prompt_or_default "Enter tag [default: craft-latest]: " "craft-latest"
         VERSION="$REPLY"
     else
-        echo "• Press Enter for latest (recommended)"
+        echo "• Press Enter for edge (recommended)"
         echo "• Type a specific tag (e.g., v0.1.0)"
         echo ""
-        prompt_or_default "Enter tag [default: latest]: " "latest"
+        prompt_or_default "Enter tag [default: edge]: " "edge"
         VERSION="$REPLY"
     fi
     echo ""
 
     if [ "$INCLUDE_CRAFT" = true ] && [ "$VERSION" = "craft-latest" ]; then
         print_info "Selected: craft-latest (Craft enabled)"
-    elif [ "$VERSION" = "latest" ]; then
-        print_info "Selected: Latest tag"
+    elif [ "$VERSION" = "edge" ]; then
+        print_info "Selected: edge (latest nightly)"
     else
         print_info "Selected: $VERSION"
     fi
@@ -1111,15 +1100,15 @@ fi
 export HOST_PORT=$AVAILABLE_PORT
 print_success "Using port $AVAILABLE_PORT for nginx"
 
-# Determine if we're using the latest tag or a craft tag (both should force pull)
+# Determine if we're using a floating tag (edge, latest, craft-*) that should force pull
 # Read IMAGE_TAG from .env file and remove any quotes or whitespace
 CURRENT_IMAGE_TAG=$(grep "^IMAGE_TAG=" "$ENV_FILE" | head -1 | cut -d'=' -f2 | tr -d ' "'"'"'')
-if [ "$CURRENT_IMAGE_TAG" = "latest" ] || [[ "$CURRENT_IMAGE_TAG" == craft-* ]]; then
+if [ "$CURRENT_IMAGE_TAG" = "edge" ] || [ "$CURRENT_IMAGE_TAG" = "latest" ] || [[ "$CURRENT_IMAGE_TAG" == craft-* ]]; then
     USE_LATEST=true
     if [[ "$CURRENT_IMAGE_TAG" == craft-* ]]; then
         print_info "Using craft tag '$CURRENT_IMAGE_TAG' - will force pull and recreate containers"
     else
-        print_info "Using 'latest' tag - will force pull and recreate containers"
+        print_info "Using '$CURRENT_IMAGE_TAG' tag - will force pull and recreate containers"
     fi
 else
     USE_LATEST=false

deployment/terraform/modules/aws/README.md

@@ -127,6 +127,7 @@ Inputs (common):
 - `name` (default `onyx`), `region` (default `us-west-2`), `tags`
 - `postgres_username`, `postgres_password`
 - `create_vpc` (default true) or existing VPC details and `s3_vpc_endpoint_id`
+- WAF controls such as `waf_allowed_ip_cidrs`, `waf_common_rule_set_count_rules`, rate limits, geo restrictions, and logging retention
 
 ### `vpc`
 - Builds a VPC sized for EKS with multiple private and public subnets

deployment/terraform/modules/aws/onyx/main.tf

@@ -88,6 +88,8 @@ module "waf" {
   tags = local.merged_tags
 
   # WAF configuration with sensible defaults
+  allowed_ip_cidrs                      = var.waf_allowed_ip_cidrs
+  common_rule_set_count_rules           = var.waf_common_rule_set_count_rules
   rate_limit_requests_per_5_minutes     = var.waf_rate_limit_requests_per_5_minutes
   api_rate_limit_requests_per_5_minutes = var.waf_api_rate_limit_requests_per_5_minutes
   geo_restriction_countries             = var.waf_geo_restriction_countries

deployment/terraform/modules/aws/onyx/variables.tf

@@ -117,6 +117,18 @@ variable "waf_rate_limit_requests_per_5_minutes" {
   default     = 2000
 }
 
+variable "waf_allowed_ip_cidrs" {
+  type        = list(string)
+  description = "Optional IPv4 CIDR ranges allowed through the WAF. Leave empty to disable IP allowlisting."
+  default     = []
+}
+
+variable "waf_common_rule_set_count_rules" {
+  type        = list(string)
+  description = "Subrules within AWSManagedRulesCommonRuleSet to override to COUNT instead of BLOCK."
+  default     = []
+}
+
 variable "waf_api_rate_limit_requests_per_5_minutes" {
   type        = number
   description = "Rate limit for API requests per 5 minutes per IP address"

deployment/terraform/modules/aws/waf/main.tf

@@ -1,6 +1,20 @@
 locals {
-  name = var.name
-  tags = var.tags
+  name                  = var.name
+  tags                  = var.tags
+  ip_allowlist_enabled  = length(var.allowed_ip_cidrs) > 0
+  managed_rule_priority = local.ip_allowlist_enabled ? 1 : 0
+}
+
+resource "aws_wafv2_ip_set" "allowed_ips" {
+  count = local.ip_allowlist_enabled ? 1 : 0
+
+  name               = "${local.name}-allowed-ips"
+  description        = "IP allowlist for ${local.name}"
+  scope              = "REGIONAL"
+  ip_address_version = "IPV4"
+  addresses          = var.allowed_ip_cidrs
+
+  tags = local.tags
 }
 
 # AWS WAFv2 Web ACL
@@ -13,10 +27,38 @@ resource "aws_wafv2_web_acl" "main" {
     allow {}
   }
 
+  dynamic "rule" {
+    for_each = local.ip_allowlist_enabled ? [1] : []
+    content {
+      name     = "BlockRequestsOutsideAllowedIPs"
+      priority = 1
+
+      action {
+        block {}
+      }
+
+      statement {
+        not_statement {
+          statement {
+            ip_set_reference_statement {
+              arn = aws_wafv2_ip_set.allowed_ips[0].arn
+            }
+          }
+        }
+      }
+
+      visibility_config {
+        cloudwatch_metrics_enabled = true
+        metric_name                = "BlockRequestsOutsideAllowedIPsMetric"
+        sampled_requests_enabled   = true
+      }
+    }
+  }
+
   # AWS Managed Rules - Core Rule Set
   rule {
     name     = "AWSManagedRulesCommonRuleSet"
-    priority = 1
+    priority = 1 + local.managed_rule_priority
 
     override_action {
       none {}
@@ -26,6 +68,16 @@ resource "aws_wafv2_web_acl" "main" {
       managed_rule_group_statement {
         name        = "AWSManagedRulesCommonRuleSet"
         vendor_name = "AWS"
+
+        dynamic "rule_action_override" {
+          for_each = var.common_rule_set_count_rules
+          content {
+            name = rule_action_override.value
+            action_to_use {
+              count {}
+            }
+          }
+        }
       }
     }
 
@@ -39,7 +91,7 @@ resource "aws_wafv2_web_acl" "main" {
   # AWS Managed Rules - Known Bad Inputs
   rule {
     name     = "AWSManagedRulesKnownBadInputsRuleSet"
-    priority = 2
+    priority = 2 + local.managed_rule_priority
 
     override_action {
       none {}
@@ -62,7 +114,7 @@ resource "aws_wafv2_web_acl" "main" {
   # Rate Limiting Rule
   rule {
     name     = "RateLimitRule"
-    priority = 3
+    priority = 3 + local.managed_rule_priority
 
     action {
       block {}
@@ -87,7 +139,7 @@ resource "aws_wafv2_web_acl" "main" {
     for_each = length(var.geo_restriction_countries) > 0 ? [1] : []
     content {
       name     = "GeoRestrictionRule"
-      priority = 4
+      priority = 4 + local.managed_rule_priority
 
       action {
         block {}
@@ -110,7 +162,7 @@ resource "aws_wafv2_web_acl" "main" {
   # IP Rate Limiting
   rule {
     name     = "APIRateLimitRule"
-    priority = 5
+    priority = 5 + local.managed_rule_priority
 
     action {
       block {}
@@ -133,7 +185,7 @@ resource "aws_wafv2_web_acl" "main" {
   # SQL Injection Protection
   rule {
     name     = "AWSManagedRulesSQLiRuleSet"
-    priority = 6
+    priority = 6 + local.managed_rule_priority
 
     override_action {
       none {}
@@ -156,7 +208,7 @@ resource "aws_wafv2_web_acl" "main" {
   # Anonymous IP Protection
   rule {
     name     = "AWSManagedRulesAnonymousIpList"
-    priority = 7
+    priority = 7 + local.managed_rule_priority
 
     override_action {
       none {}

deployment/terraform/modules/aws/waf/variables.tf

@@ -9,6 +9,18 @@ variable "tags" {
   default     = {}
 }
 
+variable "allowed_ip_cidrs" {
+  type        = list(string)
+  description = "Optional IPv4 CIDR ranges allowed to reach the application. Leave empty to disable IP allowlisting."
+  default     = []
+}
+
+variable "common_rule_set_count_rules" {
+  type        = list(string)
+  description = "Subrules within AWSManagedRulesCommonRuleSet to override to COUNT instead of BLOCK."
+  default     = []
+}
+
 variable "rate_limit_requests_per_5_minutes" {
   type        = number
   description = "Rate limit for requests per 5 minutes per IP address"

web/src/app/app/message/messageComponents/timeline/headers/CompletedHeader.tsx

@@ -56,8 +56,14 @@ function MemoryTagWithTooltip({
           side="bottom"
           className="bg-background-neutral-00 text-text-01 shadow-md max-w-[17.5rem] p-1"
           tooltip={
-            <Section flexDirection="column" gap={0.25} height="auto">
-              <div className="p-1 w-full">
+            <Section
+              flexDirection="column"
+              alignItems="start"
+              padding={0.25}
+              gap={0.25}
+              height="auto"
+            >
+              <div className="p-1">
                 <Text as="p" secondaryBody text03>
                   {memoryText}
                 </Text>
@@ -66,6 +72,7 @@ function MemoryTagWithTooltip({
                 icon={SvgAddLines}
                 title={operationLabel}
                 sizePreset="secondary"
+                paddingVariant="sm"
                 variant="body"
                 prominence="muted"
                 rightChildren={

web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx

@@ -7,11 +7,8 @@ import { processRawChatHistory } from "@/app/app/services/lib";
 import { getLatestMessageChain } from "@/app/app/services/messageTree";
 import HumanMessage from "@/app/app/message/HumanMessage";
 import AgentMessage from "@/app/app/message/messageComponents/AgentMessage";
+import { Callout } from "@/components/ui/callout";
 import OnyxInitializingLoader from "@/components/OnyxInitializingLoader";
-import { Section } from "@/layouts/general-layouts";
-import { IllustrationContent } from "@opal/layouts";
-import SvgNotFound from "@opal/illustrations/not-found";
-import { Button } from "@opal/components";
 import { Persona } from "@/app/admin/agents/interfaces";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import PreviewModal from "@/sections/modals/PreviewModal";
@@ -36,17 +33,12 @@ export default function SharedChatDisplay({
 
   if (!chatSession) {
     return (
-      <div className="h-full w-full flex flex-col items-center justify-center">
-        <Section flexDirection="column" alignItems="center" gap={1}>
-          <IllustrationContent
-            illustration={SvgNotFound}
-            title="Shared chat not found"
-            description="Did not find a shared chat with the specified ID."
-          />
-          <Button href="/app" prominence="secondary">
-            Start a new chat
-          </Button>
-        </Section>
+      <div className="min-h-full w-full">
+        <div className="mx-auto w-fit pt-8">
+          <Callout type="danger" title="Shared Chat Not Found">
+            Did not find a shared chat with the specified ID.
+          </Callout>
+        </div>
       </div>
     );
   }
@@ -59,17 +51,12 @@ export default function SharedChatDisplay({
 
   if (firstMessage === undefined) {
     return (
-      <div className="h-full w-full flex flex-col items-center justify-center">
-        <Section flexDirection="column" alignItems="center" gap={1}>
-          <IllustrationContent
-            illustration={SvgNotFound}
-            title="Shared chat not found"
-            description="No messages found in shared chat."
-          />
-          <Button href="/app" prominence="secondary">
-            Start a new chat
-          </Button>
-        </Section>
+      <div className="min-h-full w-full">
+        <div className="mx-auto w-fit pt-8">
+          <Callout type="danger" title="Shared Chat Not Found">
+            No messages found in shared chat.
+          </Callout>
+        </div>
       </div>
     );
   }

web/src/hooks/useChatSessionController.ts

@@ -61,11 +61,6 @@ interface UseChatSessionControllerProps {
   }) => Promise<void>;
 }
 
-export type SessionFetchError = {
-  type: "not_found" | "access_denied" | "unknown";
-  detail: string;
-} | null;
-
 export default function useChatSessionController({
   existingChatSessionId,
   searchParams,
@@ -85,8 +80,6 @@ export default function useChatSessionController({
   const [currentSessionFileTokenCount, setCurrentSessionFileTokenCount] =
     useState<number>(0);
   const [projectFiles, setProjectFiles] = useState<ProjectFile[]>([]);
-  const [sessionFetchError, setSessionFetchError] =
-    useState<SessionFetchError>(null);
   // Store actions
   const updateSessionAndMessageTree = useChatSessionStore(
     (state) => state.updateSessionAndMessageTree
@@ -158,8 +151,6 @@ export default function useChatSessionController({
     }
 
     async function initialSessionFetch() {
-      setSessionFetchError(null);
-
       if (existingChatSessionId === null) {
         // Clear the current session in the store to show intro messages
         setCurrentSession(null);
@@ -187,42 +178,9 @@ export default function useChatSessionController({
       setCurrentSession(existingChatSessionId);
       setIsFetchingChatMessages(existingChatSessionId, true);
 
-      let response: Response;
-      try {
-        response = await fetch(
-          `/api/chat/get-chat-session/${existingChatSessionId}`
-        );
-      } catch (error) {
-        setIsFetchingChatMessages(existingChatSessionId, false);
-        console.error("Failed to fetch chat session", {
-          chatSessionId: existingChatSessionId,
-          error,
-        });
-        setSessionFetchError({
-          type: "unknown",
-          detail: "Failed to load chat session. Please check your connection.",
-        });
-        return;
-      }
-
-      if (!response.ok) {
-        setIsFetchingChatMessages(existingChatSessionId, false);
-        let detail = "An unexpected error occurred.";
-        try {
-          const errorBody = await response.json();
-          detail = errorBody.detail || detail;
-        } catch {
-          // ignore parse errors
-        }
-        const type =
-          response.status === 404
-            ? "not_found"
-            : response.status === 403
-              ? "access_denied"
-              : "unknown";
-        setSessionFetchError({ type, detail });
-        return;
-      }
+      const response = await fetch(
+        `/api/chat/get-chat-session/${existingChatSessionId}`
+      );
 
       const session = await response.json();
       const chatSession = session as BackendChatSession;
@@ -398,6 +356,5 @@ export default function useChatSessionController({
     currentSessionFileTokenCount,
     onMessageSelection,
     projectFiles,
-    sessionFetchError,
   };
 }

web/src/layouts/app-layouts.tsx

@@ -20,10 +20,15 @@
 
 "use client";
 
-import { cn, ensureHrefProtocol, noProp } from "@/lib/utils";
+import {
+  cn,
+  ensureHrefProtocol,
+  INTERACTIVE_SELECTOR,
+  noProp,
+} from "@/lib/utils";
 import type { Components } from "react-markdown";
 import Text from "@/refresh-components/texts/Text";
-import { useCallback, useMemo, useState, useEffect } from "react";
+import { useCallback, useMemo, useRef, useState, useEffect } from "react";
 import { useAppBackground } from "@/providers/AppBackgroundProvider";
 import { useTheme } from "next-themes";
 import ShareChatSessionModal from "@/sections/modals/ShareChatSessionModal";
@@ -532,6 +537,37 @@ function Root({ children, enableBackground }: AppRootProps) {
   const { isSafari } = useBrowserInfo();
   const isLightMode = resolvedTheme === "light";
   const showBackground = hasBackground && enableBackground;
+
+  // Track whether the chat input was focused before a mousedown, so we can
+  // restore focus on mouseup if no text was selected. This preserves
+  // click-drag text selection while keeping the input focused on plain clicks.
+  const inputWasFocused = useRef(false);
+
+  const handleMouseDown = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      const activeEl = document.activeElement;
+      const isFocused =
+        activeEl instanceof HTMLElement &&
+        activeEl.id === "onyx-chat-input-textarea";
+      const target = event.target;
+      const isInteractive =
+        target instanceof HTMLElement && !!target.closest(INTERACTIVE_SELECTOR);
+      inputWasFocused.current = isFocused && !isInteractive;
+    },
+    []
+  );
+
+  const handleMouseUp = useCallback(() => {
+    if (!inputWasFocused.current) return;
+    inputWasFocused.current = false;
+    const sel = window.getSelection();
+    if (sel && !sel.isCollapsed) return;
+    const textarea = document.getElementById("onyx-chat-input-textarea");
+    // Only restore focus if no other element has grabbed it since mousedown.
+    if (textarea && document.activeElement !== textarea) {
+      textarea.focus();
+    }
+  }, []);
   const horizontalBlurMask = `linear-gradient(
     to right,
     transparent 0%,
@@ -549,6 +585,8 @@ function Root({ children, enableBackground }: AppRootProps) {
     */
     <div
       data-main-container
+      onMouseDown={handleMouseDown}
+      onMouseUp={handleMouseUp}
       className={cn(
         "@container flex flex-col h-full w-full relative overflow-hidden",
         showBackground && "bg-cover bg-center bg-fixed"

web/src/lib/constants.ts

@@ -125,7 +125,7 @@ export const MAX_FILES_TO_SHOW = 3;
 export const MOBILE_SIDEBAR_BREAKPOINT_PX = 640;
 export const DESKTOP_SMALL_BREAKPOINT_PX = 912;
 export const DESKTOP_MEDIUM_BREAKPOINT_PX = 1232;
-export const DEFAULT_AGENT_AVATAR_SIZE_PX = 18;
+export const DEFAULT_AVATAR_SIZE_PX = 18;
 export const HORIZON_DISTANCE_PX = 800;
 export const LOGO_FOLDED_SIZE_PX = 24;
 export const LOGO_UNFOLDED_SIZE_PX = 88;

web/src/lib/user.test.ts

@@ -0,0 +1,55 @@
+import { getUserInitials } from "@/lib/user";
+
+describe("getUserInitials", () => {
+  it("returns first letters of first two name parts", () => {
+    expect(getUserInitials("Alice Smith", "alice@example.com")).toBe("AS");
+  });
+
+  it("returns first two chars of a single-word name", () => {
+    expect(getUserInitials("Alice", "alice@example.com")).toBe("AL");
+  });
+
+  it("handles three-word names (uses first two)", () => {
+    expect(getUserInitials("Alice B. Smith", "alice@example.com")).toBe("AB");
+  });
+
+  it("falls back to email local part with dot separator", () => {
+    expect(getUserInitials(null, "alice.smith@example.com")).toBe("AS");
+  });
+
+  it("falls back to email local part with underscore separator", () => {
+    expect(getUserInitials(null, "alice_smith@example.com")).toBe("AS");
+  });
+
+  it("falls back to email local part with hyphen separator", () => {
+    expect(getUserInitials(null, "alice-smith@example.com")).toBe("AS");
+  });
+
+  it("uses first two chars of email local if no separator", () => {
+    expect(getUserInitials(null, "alice@example.com")).toBe("AL");
+  });
+
+  it("returns null for empty email local part", () => {
+    expect(getUserInitials(null, "@example.com")).toBeNull();
+  });
+
+  it("uppercases the result", () => {
+    expect(getUserInitials("john doe", "jd@test.com")).toBe("JD");
+  });
+
+  it("trims whitespace from name", () => {
+    expect(getUserInitials("  Alice Smith  ", "a@test.com")).toBe("AS");
+  });
+
+  it("returns null for numeric name parts", () => {
+    expect(getUserInitials("Alice 1st", "x@test.com")).toBeNull();
+  });
+
+  it("returns null for numeric email", () => {
+    expect(getUserInitials(null, "42@domain.com")).toBeNull();
+  });
+
+  it("falls back to email when name has non-alpha chars", () => {
+    expect(getUserInitials("A1", "alice@example.com")).toBe("AL");
+  });
+});

web/src/lib/user.ts

@@ -128,3 +128,54 @@ export function getUserDisplayName(user: User | null): string {
   // If nothing works, then fall back to anonymous user name
   return "Anonymous";
 }
+
+/**
+ * Derive display initials from a user's name or email.
+ *
+ * - If a name is provided, uses the first letter of the first two words.
+ * - Falls back to the email local part, splitting on `.`, `_`, or `-`.
+ * - Returns `null` when no valid alpha initials can be derived.
+ */
+export function getUserInitials(
+  name: string | null,
+  email: string
+): string | null {
+  if (name) {
+    const words = name.trim().split(/\s+/);
+    if (words.length >= 2) {
+      const first = words[0]?.[0];
+      const second = words[1]?.[0];
+      if (first && second) {
+        const result = (first + second).toUpperCase();
+        if (/^[A-Z]{2}$/.test(result)) return result;
+      }
+      return null;
+    }
+    if (name.trim().length >= 1) {
+      const result = name.trim().slice(0, 2).toUpperCase();
+      if (/^[A-Z]{1,2}$/.test(result)) return result;
+    }
+  }
+
+  const local = email.split("@")[0];
+  if (!local || local.length === 0) return null;
+  const parts = local.split(/[._-]/);
+  if (parts.length >= 2) {
+    const first = parts[0]?.[0];
+    const second = parts[1]?.[0];
+    if (first && second) {
+      const result = (first + second).toUpperCase();
+      if (/^[A-Z]{2}$/.test(result)) return result;
+    }
+    return null;
+  }
+  if (local.length >= 2) {
+    const result = local.slice(0, 2).toUpperCase();
+    if (/^[A-Z]{2}$/.test(result)) return result;
+  }
+  if (local.length === 1) {
+    const result = local.toUpperCase();
+    if (/^[A-Z]$/.test(result)) return result;
+  }
+  return null;
+}

web/src/lib/utils.ts

@@ -13,6 +13,9 @@ import { ALLOWED_URL_PROTOCOLS } from "./constants";
 const URI_SCHEME_REGEX = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
 const BARE_EMAIL_REGEX = /^[^\s@/]+@[^\s@/:]+\.[^\s@/:]+$/;
 
+export const INTERACTIVE_SELECTOR =
+  "a, button, input, textarea, select, label, [role='button'], [tabindex]:not([tabindex='-1']), [contenteditable]:not([contenteditable='false'])";
+
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }

web/src/refresh-components/avatars/AgentAvatar.tsx

@@ -4,10 +4,7 @@ import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { OnyxIcon } from "@/components/icons/icons";
 import { useSettingsContext } from "@/providers/SettingsProvider";
-import {
-  DEFAULT_AGENT_AVATAR_SIZE_PX,
-  DEFAULT_AGENT_ID,
-} from "@/lib/constants";
+import { DEFAULT_AVATAR_SIZE_PX, DEFAULT_AGENT_ID } from "@/lib/constants";
 import CustomAgentAvatar from "@/refresh-components/avatars/CustomAgentAvatar";
 import Image from "next/image";
 
@@ -18,7 +15,7 @@ export interface AgentAvatarProps {
 
 export default function AgentAvatar({
   agent,
-  size = DEFAULT_AGENT_AVATAR_SIZE_PX,
+  size = DEFAULT_AVATAR_SIZE_PX,
   ...props
 }: AgentAvatarProps) {
   const settings = useSettingsContext();

web/src/refresh-components/avatars/CustomAgentAvatar.tsx

@@ -4,7 +4,7 @@ import { cn } from "@/lib/utils";
 import type { IconProps } from "@opal/types";
 import Text from "@/refresh-components/texts/Text";
 import Image from "next/image";
-import { DEFAULT_AGENT_AVATAR_SIZE_PX } from "@/lib/constants";
+import { DEFAULT_AVATAR_SIZE_PX } from "@/lib/constants";
 import {
   SvgActivitySmall,
   SvgAudioEqSmall,
@@ -96,7 +96,7 @@ export default function CustomAgentAvatar({
   src,
   iconName,
 
-  size = DEFAULT_AGENT_AVATAR_SIZE_PX,
+  size = DEFAULT_AVATAR_SIZE_PX,
 }: CustomAgentAvatarProps) {
   if (src) {
     return (

web/src/refresh-components/avatars/UserAvatar.tsx

@@ -0,0 +1,52 @@
+import { SvgUser } from "@opal/icons";
+import { DEFAULT_AVATAR_SIZE_PX } from "@/lib/constants";
+import { getUserInitials } from "@/lib/user";
+import Text from "@/refresh-components/texts/Text";
+import type { User } from "@/lib/types";
+
+export interface UserAvatarProps {
+  user: User;
+  size?: number;
+}
+
+export default function UserAvatar({
+  user,
+  size = DEFAULT_AVATAR_SIZE_PX,
+}: UserAvatarProps) {
+  const initials = getUserInitials(
+    user.personalization?.name ?? null,
+    user.email
+  );
+
+  if (!initials) {
+    return (
+      <div
+        role="img"
+        aria-label={`${user.email} avatar`}
+        className="flex items-center justify-center rounded-full bg-background-tint-01"
+        style={{ width: size, height: size }}
+      >
+        <SvgUser size={size * 0.55} className="stroke-text-03" aria-hidden />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      role="img"
+      aria-label={`${user.email} avatar`}
+      className="flex items-center justify-center rounded-full bg-background-neutral-inverted-00"
+      style={{ width: size, height: size }}
+    >
+      <Text
+        inverted
+        secondaryAction
+        text05
+        className="select-none"
+        style={{ fontSize: size * 0.4 }}
+      >
+        {initials}
+      </Text>
+    </div>
+  );
+}

web/src/refresh-pages/AppPage.tsx

@@ -5,7 +5,6 @@ import { personaIncludesRetrieval } from "@/app/app/services/lib";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast, useToastFromQuery } from "@/hooks/useToast";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
-import { Section } from "@/layouts/general-layouts";
 import { useFederatedConnectors, useFilters, useLlmManager } from "@/lib/hooks";
 import { useForcedTools } from "@/lib/hooks/useForcedTools";
 import OnyxInitializingLoader from "@/components/OnyxInitializingLoader";
@@ -63,9 +62,6 @@ import { useShowOnboarding } from "@/hooks/useShowOnboarding";
 import * as AppLayouts from "@/layouts/app-layouts";
 import { SvgChevronDown, SvgFileText } from "@opal/icons";
 import { Button } from "@opal/components";
-import { IllustrationContent } from "@opal/layouts";
-import SvgNotFound from "@opal/illustrations/not-found";
-import SvgNoAccess from "@opal/illustrations/no-access";
 import Spacer from "@/refresh-components/Spacer";
 import useAppFocus from "@/hooks/useAppFocus";
 import { useQueryController } from "@/providers/QueryControllerProvider";
@@ -385,26 +381,23 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     setSelectedAgentFromId,
   });
 
-  const {
-    onMessageSelection,
-    currentSessionFileTokenCount,
-    sessionFetchError,
-  } = useChatSessionController({
-    existingChatSessionId: currentChatSessionId,
-    searchParams,
-    filterManager,
-    firstMessage,
-    setSelectedAgentFromId,
-    setSelectedDocuments,
-    setCurrentMessageFiles,
-    chatSessionIdRef,
-    loadedIdSessionRef,
-    chatInputBarRef,
-    isInitialLoad,
-    submitOnLoadPerformed,
-    refreshChatSessions,
-    onSubmit,
-  });
+  const { onMessageSelection, currentSessionFileTokenCount } =
+    useChatSessionController({
+      existingChatSessionId: currentChatSessionId,
+      searchParams,
+      filterManager,
+      firstMessage,
+      setSelectedAgentFromId,
+      setSelectedDocuments,
+      setCurrentMessageFiles,
+      chatSessionIdRef,
+      loadedIdSessionRef,
+      chatInputBarRef,
+      isInitialLoad,
+      submitOnLoadPerformed,
+      refreshChatSessions,
+      onSubmit,
+    });
 
   useSendMessageToParent();
 
@@ -686,10 +679,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                   {/* ChatUI */}
                   <Fade
                     show={
-                      appFocus.isChat() &&
-                      !!currentChatSessionId &&
-                      !!liveAgent &&
-                      !sessionFetchError
+                      appFocus.isChat() && !!currentChatSessionId && !!liveAgent
                     }
                     className="h-full w-full flex flex-col items-center"
                   >
@@ -718,45 +708,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                     </ChatScrollContainer>
                   </Fade>
 
-                  {/* Session fetch error (404 / 403) */}
-                  <Fade
-                    show={appFocus.isChat() && sessionFetchError !== null}
-                    className="h-full w-full flex flex-col items-center justify-center"
-                  >
-                    {sessionFetchError && (
-                      <Section
-                        flexDirection="column"
-                        alignItems="center"
-                        gap={1}
-                      >
-                        <IllustrationContent
-                          illustration={
-                            sessionFetchError.type === "access_denied"
-                              ? SvgNoAccess
-                              : SvgNotFound
-                          }
-                          title={
-                            sessionFetchError.type === "not_found"
-                              ? "Chat not found"
-                              : sessionFetchError.type === "access_denied"
-                                ? "Access denied"
-                                : "Something went wrong"
-                          }
-                          description={
-                            sessionFetchError.type === "not_found"
-                              ? "This chat session doesn't exist or has been deleted."
-                              : sessionFetchError.type === "access_denied"
-                                ? "You don't have permission to view this chat session."
-                                : sessionFetchError.detail
-                          }
-                        />
-                        <Button href="/app" prominence="secondary">
-                          Start a new chat
-                        </Button>
-                      </Section>
-                    )}
-                  </Fade>
-
                   {/* ProjectUI */}
                   {appFocus.isProject() && (
                     <div className="w-full max-h-[50vh] overflow-y-auto overscroll-y-none">
@@ -785,12 +736,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                 </div>
 
                 {/* ── Middle-center: AppInputBar ── */}
-                <div
-                  className={cn(
-                    "row-start-2 flex flex-col items-center px-4",
-                    sessionFetchError && "hidden"
-                  )}
-                >
+                <div className="row-start-2 flex flex-col items-center px-4">
                   <div className="relative w-full max-w-[var(--app-page-main-content-width)] flex flex-col">
                     {/* Scroll to bottom button - positioned absolutely above AppInputBar */}
                     {appFocus.isChat() && showScrollButton && (

web/src/refresh-pages/admin/UsersPage/UsersTable.tsx

@@ -26,7 +26,7 @@ import type {
   StatusFilter,
   StatusCountMap,
 } from "./interfaces";
-import { getInitials } from "./utils";
+import { getUserInitials } from "@/lib/user";
 
 // ---------------------------------------------------------------------------
 // Column renderers
@@ -76,7 +76,8 @@ function buildColumns(onMutate: () => void) {
   return [
     tc.qualifier({
       content: "avatar-user",
-      getInitials: (row) => getInitials(row.personal_name, row.email),
+      getInitials: (row) =>
+        getUserInitials(row.personal_name, row.email) ?? "?",
       selectable: false,
     }),
     tc.column("email", {

web/src/refresh-pages/admin/UsersPage/utils.test.ts

@@ -1,43 +0,0 @@
-import { getInitials } from "./utils";
-
-describe("getInitials", () => {
-  it("returns first letters of first two name parts", () => {
-    expect(getInitials("Alice Smith", "alice@example.com")).toBe("AS");
-  });
-
-  it("returns first two chars of a single-word name", () => {
-    expect(getInitials("Alice", "alice@example.com")).toBe("AL");
-  });
-
-  it("handles three-word names (uses first two)", () => {
-    expect(getInitials("Alice B. Smith", "alice@example.com")).toBe("AB");
-  });
-
-  it("falls back to email local part with dot separator", () => {
-    expect(getInitials(null, "alice.smith@example.com")).toBe("AS");
-  });
-
-  it("falls back to email local part with underscore separator", () => {
-    expect(getInitials(null, "alice_smith@example.com")).toBe("AS");
-  });
-
-  it("falls back to email local part with hyphen separator", () => {
-    expect(getInitials(null, "alice-smith@example.com")).toBe("AS");
-  });
-
-  it("uses first two chars of email local if no separator", () => {
-    expect(getInitials(null, "alice@example.com")).toBe("AL");
-  });
-
-  it("returns ? for empty email local part", () => {
-    expect(getInitials(null, "@example.com")).toBe("?");
-  });
-
-  it("uppercases the result", () => {
-    expect(getInitials("john doe", "jd@test.com")).toBe("JD");
-  });
-
-  it("trims whitespace from name", () => {
-    expect(getInitials("  Alice Smith  ", "a@test.com")).toBe("AS");
-  });
-});

web/src/refresh-pages/admin/UsersPage/utils.ts

@@ -1,23 +0,0 @@
-/**
- * Derive display initials from a user's name or email.
- *
- * - If a name is provided, uses the first letter of the first two words.
- * - Falls back to the email local part, splitting on `.`, `_`, or `-`.
- * - Returns at most 2 uppercase characters.
- */
-export function getInitials(name: string | null, email: string): string {
-  if (name) {
-    const parts = name.trim().split(/\s+/);
-    if (parts.length >= 2) {
-      return ((parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "")).toUpperCase();
-    }
-    return name.slice(0, 2).toUpperCase();
-  }
-  const local = email.split("@")[0];
-  if (!local) return "?";
-  const parts = local.split(/[._-]/);
-  if (parts.length >= 2) {
-    return ((parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "")).toUpperCase();
-  }
-  return local.slice(0, 2).toUpperCase();
-}

web/tests/e2e/chat/chat_session_not_found.spec.ts

@@ -1,54 +0,0 @@
-import { test, expect } from "@playwright/test";
-import { THEMES, setThemeBeforeNavigation } from "@tests/e2e/utils/theme";
-import { expectElementScreenshot } from "@tests/e2e/utils/visualRegression";
-
-const NON_EXISTENT_CHAT_ID = "00000000-0000-0000-0000-000000000000";
-
-for (const theme of THEMES) {
-  test.describe(`Chat session not found (${theme} mode)`, () => {
-    test.beforeEach(async ({ page }) => {
-      await setThemeBeforeNavigation(page, theme);
-    });
-
-    test("should show 404 page for a non-existent chat session", async ({
-      page,
-    }) => {
-      await page.goto(`/app?chatId=${NON_EXISTENT_CHAT_ID}`);
-
-      await expect(page.getByText("Chat not found")).toBeVisible({
-        timeout: 10000,
-      });
-      await expect(
-        page.getByText("This chat session doesn't exist or has been deleted.")
-      ).toBeVisible();
-      await expect(
-        page.getByRole("link", { name: "Start a new chat" })
-      ).toBeVisible();
-
-      // Sidebar should still be visible
-      await expect(page.getByTestId("AppSidebar/new-session")).toBeVisible();
-
-      const container = page.locator("[data-main-container]");
-      await expect(container).toBeVisible();
-      await expectElementScreenshot(container, {
-        name: `chat-session-not-found-${theme}`,
-      });
-    });
-
-    test("should navigate to /app when clicking Start a new chat", async ({
-      page,
-    }) => {
-      await page.goto(`/app?chatId=${NON_EXISTENT_CHAT_ID}`);
-
-      await expect(page.getByText("Chat not found")).toBeVisible({
-        timeout: 10000,
-      });
-
-      await page.getByRole("link", { name: "Start a new chat" }).click();
-      await page.waitForLoadState("networkidle");
-
-      await expect(page).toHaveURL("/app");
-      await expect(page.getByText("Chat not found")).toBeHidden();
-    });
-  });
-}

web/tests/e2e/chat/input_focus_retention.spec.ts

@@ -0,0 +1,47 @@
+import { test, expect } from "@playwright/test";
+import { loginAsWorkerUser } from "@tests/e2e/utils/auth";
+
+test.describe(`Chat Input Focus Retention`, () => {
+  test.beforeEach(async ({ page }, testInfo) => {
+    await page.context().clearCookies();
+    await loginAsWorkerUser(page, testInfo.workerIndex);
+    await page.goto("/app");
+    await page.waitForLoadState("networkidle");
+  });
+
+  test("clicking empty space retains focus on chat input", async ({ page }) => {
+    const textarea = page.locator("#onyx-chat-input-textarea");
+    await textarea.waitFor({ state: "visible", timeout: 10000 });
+
+    // Focus the textarea and type something
+    await textarea.focus();
+    await textarea.fill("test message");
+    await expect(textarea).toBeFocused();
+
+    // Click on the main container's empty space (top-left corner)
+    const container = page.locator("[data-main-container]");
+    await container.click({ position: { x: 10, y: 10 } });
+
+    // Focus should remain on the textarea
+    await expect(textarea).toBeFocused();
+  });
+
+  test("clicking interactive elements still moves focus away", async ({
+    page,
+  }) => {
+    const textarea = page.locator("#onyx-chat-input-textarea");
+    await textarea.waitFor({ state: "visible", timeout: 10000 });
+
+    // Focus the textarea
+    await textarea.focus();
+    await expect(textarea).toBeFocused();
+
+    // Click on an interactive element inside the container
+    const button = page.locator("[data-main-container] button").first();
+    await button.waitFor({ state: "visible", timeout: 5000 });
+    await button.click();
+
+    // Focus should have moved away from the textarea
+    await expect(textarea).not.toBeFocused();
+  });
+});