fix(fe): editing an LLM provider uses the global default model

Co-authored-by: Claude Opus 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 HOOKS_AVAILABLE:
+if not MULTI_TENANT and HOOK_ENABLED:
     tasks_to_schedule.append(
         {
             "name": "hook-execution-log-cleanup",

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

@@ -24,6 +24,7 @@ from onyx.configs.app_configs import MANAGED_VESPA
 from onyx.configs.app_configs import VESPA_CLOUD_CERT_PATH
 from onyx.configs.app_configs import VESPA_CLOUD_KEY_PATH
 from onyx.configs.constants import CELERY_GENERIC_BEAT_LOCK_TIMEOUT
+from onyx.configs.constants import CELERY_USER_FILE_DELETE_TASK_EXPIRES
 from onyx.configs.constants import CELERY_USER_FILE_PROCESSING_LOCK_TIMEOUT
 from onyx.configs.constants import CELERY_USER_FILE_PROCESSING_TASK_EXPIRES
 from onyx.configs.constants import CELERY_USER_FILE_PROJECT_SYNC_LOCK_TIMEOUT
@@ -33,6 +34,7 @@ from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
 from onyx.configs.constants import OnyxCeleryTask
 from onyx.configs.constants import OnyxRedisLocks
+from onyx.configs.constants import USER_FILE_DELETE_MAX_QUEUE_DEPTH
 from onyx.configs.constants import USER_FILE_PROCESSING_MAX_QUEUE_DEPTH
 from onyx.configs.constants import USER_FILE_PROJECT_SYNC_MAX_QUEUE_DEPTH
 from onyx.connectors.file.connector import LocalFileConnector
@@ -91,6 +93,17 @@ def _user_file_delete_lock_key(user_file_id: str | UUID) -> str:
     return f"{OnyxRedisLocks.USER_FILE_DELETE_LOCK_PREFIX}:{user_file_id}"
 
 
+def _user_file_delete_queued_key(user_file_id: str | UUID) -> str:
+    """Key that exists while a delete_single_user_file task is sitting in the queue.
+
+    The beat generator sets this with a TTL equal to CELERY_USER_FILE_DELETE_TASK_EXPIRES
+    before enqueuing and the worker deletes it as its first action.  This prevents
+    the beat from adding duplicate tasks for files that already have a live task
+    in flight.
+    """
+    return f"{OnyxRedisLocks.USER_FILE_DELETE_QUEUED_PREFIX}:{user_file_id}"
+
+
 def get_user_file_project_sync_queue_depth(celery_app: Celery) -> int:
     redis_celery: Redis = celery_app.broker_connection().channel().client  # type: ignore
     return celery_get_queue_length(
@@ -546,7 +559,23 @@ def process_single_user_file(
     ignore_result=True,
 )
 def check_for_user_file_delete(self: Task, *, tenant_id: str) -> None:
-    """Scan for user files with DELETING status and enqueue per-file tasks."""
+    """Scan for user files with DELETING status and enqueue per-file tasks.
+
+    Three mechanisms prevent queue runaway (mirrors check_user_file_processing):
+
+    1. **Queue depth backpressure** – if the broker queue already has more than
+       USER_FILE_DELETE_MAX_QUEUE_DEPTH items we skip this beat cycle entirely.
+
+    2. **Per-file queued guard** – before enqueuing a task we set a short-lived
+       Redis key (TTL = CELERY_USER_FILE_DELETE_TASK_EXPIRES).  If that key
+       already exists the file already has a live task in the queue, so we skip
+       it.  The worker deletes the key the moment it picks up the task so the
+       next beat cycle can re-enqueue if the file is still DELETING.
+
+    3. **Task expiry** – every enqueued task carries an `expires` value equal to
+       CELERY_USER_FILE_DELETE_TASK_EXPIRES.  If a task is still sitting in
+       the queue after that deadline, Celery discards it without touching the DB.
+    """
     task_logger.info("check_for_user_file_delete - Starting")
     redis_client = get_redis_client(tenant_id=tenant_id)
     lock: RedisLock = redis_client.lock(
@@ -555,8 +584,23 @@ def check_for_user_file_delete(self: Task, *, tenant_id: str) -> None:
     )
     if not lock.acquire(blocking=False):
         return None
+
     enqueued = 0
+    skipped_guard = 0
     try:
+        # --- Protection 1: queue depth backpressure ---
+        # NOTE: must use the broker's Redis client (not redis_client) because
+        # Celery queues live on a separate Redis DB with CELERY_SEPARATOR keys.
+        r_celery: Redis = self.app.broker_connection().channel().client  # type: ignore
+        queue_len = celery_get_queue_length(OnyxCeleryQueues.USER_FILE_DELETE, r_celery)
+        if queue_len > USER_FILE_DELETE_MAX_QUEUE_DEPTH:
+            task_logger.warning(
+                f"check_for_user_file_delete - Queue depth {queue_len} exceeds "
+                f"{USER_FILE_DELETE_MAX_QUEUE_DEPTH}, skipping enqueue for "
+                f"tenant={tenant_id}"
+            )
+            return None
+
         with get_session_with_current_tenant() as db_session:
             user_file_ids = (
                 db_session.execute(
@@ -568,23 +612,40 @@ def check_for_user_file_delete(self: Task, *, tenant_id: str) -> None:
                 .all()
             )
             for user_file_id in user_file_ids:
-                self.app.send_task(
-                    OnyxCeleryTask.DELETE_SINGLE_USER_FILE,
-                    kwargs={"user_file_id": str(user_file_id), "tenant_id": tenant_id},
-                    queue=OnyxCeleryQueues.USER_FILE_DELETE,
-                    priority=OnyxCeleryPriority.HIGH,
+                # --- Protection 2: per-file queued guard ---
+                queued_key = _user_file_delete_queued_key(user_file_id)
+                guard_set = redis_client.set(
+                    queued_key,
+                    1,
+                    ex=CELERY_USER_FILE_DELETE_TASK_EXPIRES,
+                    nx=True,
                 )
+                if not guard_set:
+                    skipped_guard += 1
+                    continue
+
+                # --- Protection 3: task expiry ---
+                try:
+                    self.app.send_task(
+                        OnyxCeleryTask.DELETE_SINGLE_USER_FILE,
+                        kwargs={
+                            "user_file_id": str(user_file_id),
+                            "tenant_id": tenant_id,
+                        },
+                        queue=OnyxCeleryQueues.USER_FILE_DELETE,
+                        priority=OnyxCeleryPriority.HIGH,
+                        expires=CELERY_USER_FILE_DELETE_TASK_EXPIRES,
+                    )
+                except Exception:
+                    redis_client.delete(queued_key)
+                    raise
                 enqueued += 1
-    except Exception as e:
-        task_logger.exception(
-            f"check_for_user_file_delete - Error enqueuing deletes - {e.__class__.__name__}"
-        )
-        return None
     finally:
         if lock.owned():
             lock.release()
+
     task_logger.info(
-        f"check_for_user_file_delete - Enqueued {enqueued} tasks for tenant={tenant_id}"
+        f"check_for_user_file_delete - Enqueued {enqueued} tasks, skipped_guard={skipped_guard} for tenant={tenant_id}"
     )
     return None
 
@@ -602,6 +663,9 @@ def delete_user_file_impl(
     file_lock: RedisLock | None = None
     if redis_locking:
         redis_client = get_redis_client(tenant_id=tenant_id)
+        # Clear the queued guard so the beat can re-enqueue if deletion fails
+        # and the file remains in DELETING status.
+        redis_client.delete(_user_file_delete_queued_key(user_file_id))
         file_lock = redis_client.lock(
             _user_file_delete_lock_key(user_file_id),
             timeout=CELERY_GENERIC_BEAT_LOCK_TIMEOUT,

backend/onyx/configs/app_configs.py

@@ -278,14 +278,17 @@ USING_AWS_MANAGED_OPENSEARCH = (
 OPENSEARCH_PROFILING_DISABLED = (
     os.environ.get("OPENSEARCH_PROFILING_DISABLED", "").lower() == "true"
 )
-
+# Whether to disable match highlights for OpenSearch. Defaults to True for now
+# as we investigate query performance.
+OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED = (
+    os.environ.get("OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED", "true").lower() == "true"
+)
 # When enabled, OpenSearch returns detailed score breakdowns for each hit.
 # Useful for debugging and tuning search relevance. Has ~10-30% performance overhead according to documentation.
 # Seems for Hybrid Search in practice, the impact is actually more like 1000x slower.
 OPENSEARCH_EXPLAIN_ENABLED = (
     os.environ.get("OPENSEARCH_EXPLAIN_ENABLED", "").lower() == "true"
 )
-
 # Analyzer used for full-text fields (title, content). Use OpenSearch built-in analyzer
 # names (e.g. "english", "standard", "german"). Affects stemming and tokenization;
 # existing indices need reindexing after a change.

backend/onyx/configs/constants.py

@@ -177,6 +177,14 @@ USER_FILE_PROJECT_SYNC_MAX_QUEUE_DEPTH = 500
 
 CELERY_USER_FILE_PROJECT_SYNC_LOCK_TIMEOUT = 5 * 60  # 5 minutes (in seconds)
 
+# How long a queued user-file-delete task is valid before workers discard it.
+# Mirrors the processing task expiry to prevent indefinite queue growth when
+# files are stuck in DELETING status and the beat keeps re-enqueuing them.
+CELERY_USER_FILE_DELETE_TASK_EXPIRES = 60  # 1 minute (in seconds)
+
+# Max queue depth before the delete beat stops enqueuing more delete tasks.
+USER_FILE_DELETE_MAX_QUEUE_DEPTH = 500
+
 CELERY_SANDBOX_FILE_SYNC_LOCK_TIMEOUT = 5 * 60  # 5 minutes (in seconds)
 
 DANSWER_REDIS_FUNCTION_LOCK_PREFIX = "da_function_lock:"
@@ -469,6 +477,9 @@ class OnyxRedisLocks:
     USER_FILE_PROJECT_SYNC_QUEUED_PREFIX = "da_lock:user_file_project_sync_queued"
     USER_FILE_DELETE_BEAT_LOCK = "da_lock:check_user_file_delete_beat"
     USER_FILE_DELETE_LOCK_PREFIX = "da_lock:user_file_delete"
+    # Short-lived key set when a delete task is enqueued; cleared when the worker picks it up.
+    # Prevents the beat from re-enqueuing the same file while a delete task is already queued.
+    USER_FILE_DELETE_QUEUED_PREFIX = "da_lock:user_file_delete_queued"
 
     # Release notes
     RELEASE_NOTES_FETCH_LOCK = "da_lock:release_notes_fetch"

backend/onyx/db/projects.py

@@ -12,6 +12,7 @@ from sqlalchemy.orm import Session
 from starlette.background import BackgroundTasks
 
 from onyx.configs.app_configs import DISABLE_VECTOR_DB
+from onyx.configs.constants import CELERY_USER_FILE_PROCESSING_TASK_EXPIRES
 from onyx.configs.constants import FileOrigin
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
@@ -144,6 +145,7 @@ def upload_files_to_user_files_with_indexing(
                 kwargs={"user_file_id": user_file.id, "tenant_id": tenant_id},
                 queue=OnyxCeleryQueues.USER_FILE_PROCESSING,
                 priority=OnyxCeleryPriority.HIGH,
+                expires=CELERY_USER_FILE_PROCESSING_TASK_EXPIRES,
             )
             logger.info(
                 f"Triggered indexing for user_file_id={user_file.id} with task_id={task.id}"

backend/onyx/document_index/opensearch/search.py

@@ -7,6 +7,7 @@ from uuid import UUID
 
 from onyx.configs.app_configs import DEFAULT_OPENSEARCH_QUERY_TIMEOUT_S
 from onyx.configs.app_configs import OPENSEARCH_EXPLAIN_ENABLED
+from onyx.configs.app_configs import OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED
 from onyx.configs.app_configs import OPENSEARCH_PROFILING_DISABLED
 from onyx.configs.constants import DocumentSource
 from onyx.configs.constants import INDEX_SEPARATOR
@@ -364,9 +365,6 @@ class DocumentQuery:
             attached_document_ids=index_filters.attached_document_ids,
             hierarchy_node_ids=index_filters.hierarchy_node_ids,
         )
-        match_highlights_configuration = (
-            DocumentQuery._get_match_highlights_configuration()
-        )
 
         # See https://docs.opensearch.org/latest/query-dsl/compound/hybrid/
         hybrid_search_query: dict[str, Any] = {
@@ -393,7 +391,6 @@ class DocumentQuery:
         final_hybrid_search_body: dict[str, Any] = {
             "query": hybrid_search_query,
             "size": num_hits,
-            "highlight": match_highlights_configuration,
             "timeout": f"{DEFAULT_OPENSEARCH_QUERY_TIMEOUT_S}s",
             # Exclude retrieving the vector fields in order to save on
             # retrieval cost as we don't need them upstream.
@@ -402,6 +399,11 @@ class DocumentQuery:
             },
         }
 
+        if not OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED:
+            final_hybrid_search_body["highlight"] = (
+                DocumentQuery._get_match_highlights_configuration()
+            )
+
         # Explain is for scoring breakdowns.
         if OPENSEARCH_EXPLAIN_ENABLED:
             final_hybrid_search_body["explain"] = True

backend/onyx/error_handling/error_codes.py

@@ -88,7 +88,6 @@ 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_processing/image_summarization.py

@@ -88,9 +88,13 @@ def summarize_image_with_error_handling(
     try:
         return summarize_image_pipeline(llm, image_data, user_prompt, system_prompt)
     except UnsupportedImageFormatError:
+        magic_hex = image_data[:8].hex() if image_data else "empty"
         logger.info(
-            "Skipping image summarization due to unsupported MIME type for %s",
+            "Skipping image summarization due to unsupported MIME type "
+            "for %s (magic_bytes=%s, size=%d bytes)",
             context_name,
+            magic_hex,
+            len(image_data),
         )
         return None
 
@@ -134,9 +138,23 @@ def _summarize_image(
         return summary
 
     except Exception as e:
-        error_msg = f"Summarization failed. Messages: {messages}"
-        error_msg = error_msg[:1024]
-        raise ValueError(error_msg) from e
+        # Extract structured details from LiteLLM exceptions when available,
+        # rather than dumping the full messages payload (which contains base64
+        # image data and produces enormous, unreadable error logs).
+        str_e = str(e)
+        if len(str_e) > 512:
+            str_e = str_e[:512] + "... (truncated)"
+        parts = [f"Summarization failed: {type(e).__name__}: {str_e}"]
+        status_code = getattr(e, "status_code", None)
+        llm_provider = getattr(e, "llm_provider", None)
+        model = getattr(e, "model", None)
+        if status_code is not None:
+            parts.append(f"status_code={status_code}")
+        if llm_provider is not None:
+            parts.append(f"llm_provider={llm_provider}")
+        if model is not None:
+            parts.append(f"model={model}")
+        raise ValueError(" | ".join(parts)) from e
 
 
 def _encode_image_for_llm_prompt(image_data: bytes) -> str:

backend/onyx/hooks/executor.py

@@ -1,330 +0,0 @@
-"""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

@@ -0,0 +1,127 @@
+from datetime import datetime
+from enum import Enum
+from typing import Annotated
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic import field_validator
+from pydantic import model_validator
+from pydantic import SecretStr
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+
+NonEmptySecretStr = Annotated[SecretStr, Field(min_length=1)]
+
+
+# ---------------------------------------------------------------------------
+# Request models
+# ---------------------------------------------------------------------------
+
+
+class HookCreateRequest(BaseModel):
+    name: str = Field(min_length=1)
+    hook_point: HookPoint
+    endpoint_url: str = Field(min_length=1)
+    api_key: NonEmptySecretStr | None = None
+    fail_strategy: HookFailStrategy | None = None  # if None, uses HookPointSpec default
+    timeout_seconds: float | None = Field(
+        default=None, gt=0
+    )  # if None, uses HookPointSpec default
+
+    @field_validator("name", "endpoint_url")
+    @classmethod
+    def no_whitespace_only(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("cannot be whitespace-only.")
+        return v
+
+
+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
+
+    @model_validator(mode="after")
+    def require_at_least_one_field(self) -> "HookUpdateRequest":
+        if not self.model_fields_set:
+            raise ValueError("At least one field must be provided for an update.")
+        if "name" in self.model_fields_set and not (self.name or "").strip():
+            raise ValueError("name cannot be cleared.")
+        if (
+            "endpoint_url" in self.model_fields_set
+            and not (self.endpoint_url or "").strip()
+        ):
+            raise ValueError("endpoint_url cannot be cleared.")
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class HookPointMetaResponse(BaseModel):
+    hook_point: HookPoint
+    display_name: str
+    description: str
+    docs_url: str | None
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any]
+    default_timeout_seconds: float
+    default_fail_strategy: HookFailStrategy
+    fail_hard_description: str
+
+
+class HookResponse(BaseModel):
+    id: int
+    name: str
+    hook_point: HookPoint
+    # Nullable to match the DB column — endpoint_url is required on creation but
+    # future hook point types may not use an external endpoint (e.g. built-in handlers).
+    endpoint_url: str | None
+    fail_strategy: HookFailStrategy
+    timeout_seconds: float  # always resolved — None from request is replaced with spec default before DB write
+    is_active: bool
+    creator_email: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class HookValidateResponse(BaseModel):
+    success: bool
+    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):
+    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

@@ -0,0 +1,59 @@
+from abc import ABC
+from abc import abstractmethod
+from typing import Any
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+
+
+_REQUIRED_ATTRS = (
+    "hook_point",
+    "display_name",
+    "description",
+    "default_timeout_seconds",
+    "fail_hard_description",
+    "default_fail_strategy",
+)
+
+
+class HookPointSpec(ABC):
+    """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.
+
+    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.
+    """
+
+    hook_point: HookPoint
+    display_name: str
+    description: str
+    default_timeout_seconds: float
+    fail_hard_description: str
+    default_fail_strategy: HookFailStrategy
+    docs_url: str | None = None
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        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."""

backend/onyx/hooks/points/document_ingestion.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.hooks.points.base import HookPointSpec
+
+
+class DocumentIngestionSpec(HookPointSpec):
+    """Hook point that runs during document ingestion.
+
+    # TODO(@Bo-Onyx): define call site, input/output schema, and timeout budget.
+    """
+
+    hook_point = HookPoint.DOCUMENT_INGESTION
+    display_name = "Document Ingestion"
+    description = "Runs during document ingestion. Allows filtering or transforming documents before indexing."
+    default_timeout_seconds = 30.0
+    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": {}}

backend/onyx/hooks/points/query_processing.py

@@ -0,0 +1,83 @@
+from typing import Any
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.hooks.points.base import HookPointSpec
+
+
+class QueryProcessingSpec(HookPointSpec):
+    """Hook point that runs on every user query before it enters the pipeline.
+
+    Call site: inside handle_stream_message_objects() in
+    backend/onyx/chat/process_message.py, immediately after message_text is
+    assigned from the request and before create_new_chat_message() saves it.
+
+    This is the earliest possible point in the query pipeline:
+    - Raw query — unmodified, exactly as the user typed it
+    - No side effects yet — message has not been saved to DB
+    - User identity is available for user-specific logic
+
+    Supported use cases:
+    - Query rejection: block queries based on content or user context
+    - Query rewriting: normalize, expand, or modify the query
+    - PII removal: scrub sensitive data before the LLM sees it
+    - Access control: reject queries from certain users or groups
+    - Query auditing: log or track queries based on business rules
+    """
+
+    hook_point = HookPoint.QUERY_PROCESSING
+    display_name = "Query Processing"
+    description = (
+        "Runs on every user query before it enters the pipeline. "
+        "Allows rewriting, filtering, or rejecting queries."
+    )
+    default_timeout_seconds = 5.0  # user is actively waiting — keep tight
+    fail_hard_description = (
+        "The query will be blocked and the user will see an error message."
+    )
+    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"],
+        }

backend/onyx/hooks/registry.py

@@ -0,0 +1,45 @@
+from onyx.db.enums import HookPoint
+from onyx.hooks.points.base import HookPointSpec
+from onyx.hooks.points.document_ingestion import DocumentIngestionSpec
+from onyx.hooks.points.query_processing import QueryProcessingSpec
+
+# Internal: use `monkeypatch.setattr(registry_module, "_REGISTRY", {...})` to override in tests.
+_REGISTRY: dict[HookPoint, HookPointSpec] = {
+    HookPoint.DOCUMENT_INGESTION: DocumentIngestionSpec(),
+    HookPoint.QUERY_PROCESSING: QueryProcessingSpec(),
+}
+
+
+def validate_registry() -> None:
+    """Assert that every HookPoint enum value has a registered spec.
+
+    Call once at application startup (e.g. from the FastAPI lifespan hook).
+    Raises RuntimeError if any hook point is missing a spec.
+    """
+    missing = set(HookPoint) - set(_REGISTRY)
+    if missing:
+        raise RuntimeError(
+            f"Hook point(s) have no registered spec: {missing}. "
+            "Add an entry to onyx.hooks.registry._REGISTRY."
+        )
+
+
+def get_hook_point_spec(hook_point: HookPoint) -> HookPointSpec:
+    """Returns the spec for a given hook point.
+
+    Raises ValueError if the hook point has no registered spec — this is a
+    programmer error; every HookPoint enum value must have a corresponding spec
+    in _REGISTRY.
+    """
+    try:
+        return _REGISTRY[hook_point]
+    except KeyError:
+        raise ValueError(
+            f"No spec registered for hook point {hook_point!r}. "
+            "Add an entry to onyx.hooks.registry._REGISTRY."
+        )
+
+
+def get_all_specs() -> list[HookPointSpec]:
+    """Returns the specs for all registered hook points."""
+    return list(_REGISTRY.values())

backend/onyx/hooks/utils.py

@@ -1,5 +0,0 @@
-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/indexing/indexing_pipeline.py

@@ -395,6 +395,12 @@ def process_image_sections(documents: list[Document]) -> list[IndexingDocument]:
         llm = get_default_llm_with_vision()
 
     if not llm:
+        if get_image_extraction_and_analysis_enabled():
+            logger.warning(
+                "Image analysis is enabled but no vision-capable LLM is "
+                "available — images will not be summarized. Configure a "
+                "vision model in the admin LLM settings."
+            )
         # Even without LLM, we still convert to IndexingDocument with base Sections
         return [
             IndexingDocument(

backend/onyx/llm/factory.py

@@ -168,10 +168,23 @@ def get_default_llm_with_vision(
             if model_supports_image_input(
                 default_model.name, default_model.llm_provider.provider
             ):
+                logger.info(
+                    "Using default vision model: %s (provider=%s)",
+                    default_model.name,
+                    default_model.llm_provider.provider,
+                )
                 return create_vision_llm(
                     LLMProviderView.from_model(default_model.llm_provider),
                     default_model.name,
                 )
+            else:
+                logger.warning(
+                    "Default vision model %s (provider=%s) does not support "
+                    "image input — falling back to searching all providers",
+                    default_model.name,
+                    default_model.llm_provider.provider,
+                )
+
         # Fall back to searching all providers
         models = fetch_existing_models(
             db_session=db_session,
@@ -179,6 +192,10 @@ def get_default_llm_with_vision(
         )
 
         if not models:
+            logger.warning(
+                "No LLM models with VISION or CHAT flow type found — "
+                "image summarization will be disabled"
+            )
             return None
 
         for model in models:
@@ -200,11 +217,25 @@ def get_default_llm_with_vision(
 
     for model in sorted_models:
         if model_supports_image_input(model.name, model.llm_provider.provider):
+            logger.info(
+                "Using fallback vision model: %s (provider=%s)",
+                model.name,
+                model.llm_provider.provider,
+            )
             return create_vision_llm(
                 provider_map[model.llm_provider_id],
                 model.name,
             )
 
+    checked_models = [
+        f"{m.name} (provider={m.llm_provider.provider})" for m in sorted_models
+    ]
+    logger.warning(
+        "No vision-capable model found among %d candidates: %s — "
+        "image summarization will be disabled",
+        len(sorted_models),
+        ", ".join(checked_models),
+    )
     return None
 
 

backend/onyx/main.py

@@ -62,6 +62,7 @@ from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.engine.sql_engine import SqlEngine
 from onyx.error_handling.exceptions import register_onyx_exception_handlers
 from onyx.file_store.file_store import get_default_file_store
+from onyx.hooks.registry import validate_registry
 from onyx.server.api_key.api import router as api_key_router
 from onyx.server.auth_check import check_router_auth
 from onyx.server.documents.cc_pair import router as cc_pair_router
@@ -308,6 +309,7 @@ def validate_no_vector_db_settings() -> None:
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:  # noqa: ARG001
     validate_no_vector_db_settings()
     validate_cache_backend_settings()
+    validate_registry()
 
     # Set recursion limit
     if SYSTEM_RECURSION_LIMIT is not None:

backend/onyx/tools/tool_implementations/python/python_tool.py

@@ -1,3 +1,4 @@
+import hashlib
 import mimetypes
 from io import BytesIO
 from typing import Any
@@ -83,6 +84,14 @@ class PythonTool(Tool[PythonToolOverrideKwargs]):
     def __init__(self, tool_id: int, emitter: Emitter) -> None:
         super().__init__(emitter=emitter)
         self._id = tool_id
+        # Cache of (filename, content_hash) -> ci_file_id to avoid re-uploading
+        # the same file on every tool call iteration within the same agent session.
+        # Filename is included in the key so two files with identical bytes but
+        # different names each get their own upload slot.
+        # TTL assumption: code-interpreter file TTLs (typically hours) greatly
+        # exceed the lifetime of a single agent session (at most MAX_LLM_CYCLES
+        # iterations, typically a few minutes), so stale-ID eviction is not needed.
+        self._uploaded_file_cache: dict[tuple[str, str], str] = {}
 
     @property
     def id(self) -> int:
@@ -182,8 +191,13 @@ class PythonTool(Tool[PythonToolOverrideKwargs]):
             for ind, chat_file in enumerate(chat_files):
                 file_name = chat_file.filename or f"file_{ind}"
                 try:
-                    # Upload to Code Interpreter
-                    ci_file_id = client.upload_file(chat_file.content, file_name)
+                    content_hash = hashlib.sha256(chat_file.content).hexdigest()
+                    cache_key = (file_name, content_hash)
+                    ci_file_id = self._uploaded_file_cache.get(cache_key)
+                    if ci_file_id is None:
+                        # Upload to Code Interpreter
+                        ci_file_id = client.upload_file(chat_file.content, file_name)
+                        self._uploaded_file_cache[cache_key] = ci_file_id
 
                     # Stage for execution
                     files_to_stage.append({"path": file_name, "file_id": ci_file_id})
@@ -299,14 +313,10 @@ class PythonTool(Tool[PythonToolOverrideKwargs]):
                             f"Failed to delete Code Interpreter generated file {ci_file_id}: {e}"
                         )
 
-                # Cleanup staged input files
-                for file_mapping in files_to_stage:
-                    try:
-                        client.delete_file(file_mapping["file_id"])
-                    except Exception as e:
-                        logger.error(
-                            f"Failed to delete Code Interpreter staged file {file_mapping['file_id']}: {e}"
-                        )
+                # Note: staged input files are intentionally not deleted here because
+                # _uploaded_file_cache reuses their file_ids across iterations. They are
+                # orphaned when the session ends, but the code interpreter cleans up
+                # stale files on its own TTL.
 
                 # Emit file_ids once files are processed
                 if generated_file_ids:

backend/tests/external_dependency_unit/celery/test_user_file_delete_queue.py

@@ -0,0 +1,274 @@
+"""
+External dependency unit tests for user file delete queue protections.
+
+Verifies that the three mechanisms added to check_for_user_file_delete work
+correctly:
+
+1. Queue depth backpressure – when the broker queue exceeds
+   USER_FILE_DELETE_MAX_QUEUE_DEPTH, no new tasks are enqueued.
+
+2. Per-file Redis guard key – if the guard key for a file already exists in
+   Redis, that file is skipped even though it is still in DELETING status.
+
+3. Task expiry – every send_task call carries expires=
+   CELERY_USER_FILE_DELETE_TASK_EXPIRES so that stale queued tasks are
+   discarded by workers automatically.
+
+Also verifies that delete_user_file_impl clears the guard key the moment
+it is picked up by a worker.
+
+Uses real Redis (DB 0 via get_redis_client) and real PostgreSQL for UserFile
+rows.  The Celery app is provided as a MagicMock injected via a PropertyMock
+on the task class so no real broker is needed.
+"""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+from unittest.mock import MagicMock
+from unittest.mock import patch
+from unittest.mock import PropertyMock
+from uuid import uuid4
+
+from sqlalchemy.orm import Session
+
+from onyx.background.celery.tasks.user_file_processing.tasks import (
+    _user_file_delete_lock_key,
+)
+from onyx.background.celery.tasks.user_file_processing.tasks import (
+    _user_file_delete_queued_key,
+)
+from onyx.background.celery.tasks.user_file_processing.tasks import (
+    check_for_user_file_delete,
+)
+from onyx.background.celery.tasks.user_file_processing.tasks import (
+    process_single_user_file_delete,
+)
+from onyx.configs.constants import CELERY_USER_FILE_DELETE_TASK_EXPIRES
+from onyx.configs.constants import OnyxCeleryQueues
+from onyx.configs.constants import OnyxCeleryTask
+from onyx.configs.constants import USER_FILE_DELETE_MAX_QUEUE_DEPTH
+from onyx.db.enums import UserFileStatus
+from onyx.db.models import UserFile
+from onyx.redis.redis_pool import get_redis_client
+from tests.external_dependency_unit.conftest import create_test_user
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_PATCH_QUEUE_LEN = (
+    "onyx.background.celery.tasks.user_file_processing.tasks.celery_get_queue_length"
+)
+
+
+def _create_deleting_user_file(db_session: Session, user_id: object) -> UserFile:
+    """Insert a UserFile in DELETING status and return it."""
+    uf = UserFile(
+        id=uuid4(),
+        user_id=user_id,
+        file_id=f"test_file_{uuid4().hex[:8]}",
+        name=f"test_{uuid4().hex[:8]}.txt",
+        file_type="text/plain",
+        status=UserFileStatus.DELETING,
+    )
+    db_session.add(uf)
+    db_session.commit()
+    db_session.refresh(uf)
+    return uf
+
+
+@contextmanager
+def _patch_task_app(task: Any, mock_app: MagicMock) -> Generator[None, None, None]:
+    """Patch the ``app`` property on *task*'s class so that ``self.app``
+    inside the task function returns *mock_app*.
+
+    With ``bind=True``, ``task.run`` is a bound method whose ``__self__`` is
+    the actual task instance.  We patch ``app`` on that instance's class
+    (a unique Celery-generated Task subclass) so the mock is scoped to this
+    task only.
+    """
+    task_instance = task.run.__self__
+    with patch.object(
+        type(task_instance), "app", new_callable=PropertyMock, return_value=mock_app
+    ):
+        yield
+
+
+# ---------------------------------------------------------------------------
+# Test classes
+# ---------------------------------------------------------------------------
+
+
+class TestDeleteQueueDepthBackpressure:
+    """Protection 1: skip all enqueuing when the broker queue is too deep."""
+
+    def test_no_tasks_enqueued_when_queue_over_limit(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+    ) -> None:
+        """When the queue depth exceeds the limit the beat cycle is skipped."""
+        user = create_test_user(db_session, "del_bp_user")
+        _create_deleting_user_file(db_session, user.id)
+
+        mock_app = MagicMock()
+
+        with (
+            _patch_task_app(check_for_user_file_delete, mock_app),
+            patch(_PATCH_QUEUE_LEN, return_value=USER_FILE_DELETE_MAX_QUEUE_DEPTH + 1),
+        ):
+            check_for_user_file_delete.run(tenant_id=TEST_TENANT_ID)
+
+        mock_app.send_task.assert_not_called()
+
+
+class TestDeletePerFileGuardKey:
+    """Protection 2: per-file Redis guard key prevents duplicate enqueue."""
+
+    def test_guarded_file_not_re_enqueued(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+    ) -> None:
+        """A file whose guard key is already set in Redis is skipped."""
+        user = create_test_user(db_session, "del_guard_user")
+        uf = _create_deleting_user_file(db_session, user.id)
+
+        redis_client = get_redis_client(tenant_id=TEST_TENANT_ID)
+        guard_key = _user_file_delete_queued_key(uf.id)
+        redis_client.setex(guard_key, CELERY_USER_FILE_DELETE_TASK_EXPIRES, 1)
+
+        mock_app = MagicMock()
+
+        try:
+            with (
+                _patch_task_app(check_for_user_file_delete, mock_app),
+                patch(_PATCH_QUEUE_LEN, return_value=0),
+            ):
+                check_for_user_file_delete.run(tenant_id=TEST_TENANT_ID)
+
+            # send_task must not have been called with this specific file's ID
+            for call in mock_app.send_task.call_args_list:
+                kwargs = call.kwargs.get("kwargs", {})
+                assert kwargs.get("user_file_id") != str(
+                    uf.id
+                ), f"File {uf.id} should have been skipped because its guard key exists"
+        finally:
+            redis_client.delete(guard_key)
+
+    def test_guard_key_exists_in_redis_after_enqueue(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+    ) -> None:
+        """After a file is enqueued its guard key is present in Redis with a TTL."""
+        user = create_test_user(db_session, "del_guard_set_user")
+        uf = _create_deleting_user_file(db_session, user.id)
+
+        redis_client = get_redis_client(tenant_id=TEST_TENANT_ID)
+        guard_key = _user_file_delete_queued_key(uf.id)
+        redis_client.delete(guard_key)  # clean slate
+
+        mock_app = MagicMock()
+
+        try:
+            with (
+                _patch_task_app(check_for_user_file_delete, mock_app),
+                patch(_PATCH_QUEUE_LEN, return_value=0),
+            ):
+                check_for_user_file_delete.run(tenant_id=TEST_TENANT_ID)
+
+            assert redis_client.exists(
+                guard_key
+            ), "Guard key should be set in Redis after enqueue"
+            ttl = int(redis_client.ttl(guard_key))  # type: ignore[arg-type]
+            assert (
+                0 < ttl <= CELERY_USER_FILE_DELETE_TASK_EXPIRES
+            ), f"Guard key TTL {ttl}s is outside the expected range (0, {CELERY_USER_FILE_DELETE_TASK_EXPIRES}]"
+        finally:
+            redis_client.delete(guard_key)
+
+
+class TestDeleteTaskExpiry:
+    """Protection 3: every send_task call includes an expires value."""
+
+    def test_send_task_called_with_expires(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+    ) -> None:
+        """send_task is called with the correct queue, task name, and expires."""
+        user = create_test_user(db_session, "del_expires_user")
+        uf = _create_deleting_user_file(db_session, user.id)
+
+        redis_client = get_redis_client(tenant_id=TEST_TENANT_ID)
+        guard_key = _user_file_delete_queued_key(uf.id)
+        redis_client.delete(guard_key)
+
+        mock_app = MagicMock()
+
+        try:
+            with (
+                _patch_task_app(check_for_user_file_delete, mock_app),
+                patch(_PATCH_QUEUE_LEN, return_value=0),
+            ):
+                check_for_user_file_delete.run(tenant_id=TEST_TENANT_ID)
+
+            # At least one task should have been submitted (for our file)
+            assert (
+                mock_app.send_task.call_count >= 1
+            ), "Expected at least one task to be submitted"
+
+            # Every submitted task must carry expires
+            for call in mock_app.send_task.call_args_list:
+                assert call.args[0] == OnyxCeleryTask.DELETE_SINGLE_USER_FILE
+                assert call.kwargs.get("queue") == OnyxCeleryQueues.USER_FILE_DELETE
+                assert (
+                    call.kwargs.get("expires") == CELERY_USER_FILE_DELETE_TASK_EXPIRES
+                ), "Task must be submitted with the correct expires value to prevent stale task accumulation"
+        finally:
+            redis_client.delete(guard_key)
+
+
+class TestDeleteWorkerClearsGuardKey:
+    """process_single_user_file_delete removes the guard key when it picks up a task."""
+
+    def test_guard_key_deleted_on_pickup(
+        self,
+        tenant_context: None,  # noqa: ARG002
+    ) -> None:
+        """The guard key is deleted before the worker does any real work.
+
+        We simulate an already-locked file so delete_user_file_impl returns
+        early – but crucially, after the guard key deletion.
+        """
+        user_file_id = str(uuid4())
+
+        redis_client = get_redis_client(tenant_id=TEST_TENANT_ID)
+        guard_key = _user_file_delete_queued_key(user_file_id)
+
+        # Simulate the guard key set when the beat enqueued the task
+        redis_client.setex(guard_key, CELERY_USER_FILE_DELETE_TASK_EXPIRES, 1)
+        assert redis_client.exists(guard_key), "Guard key must exist before pickup"
+
+        # Hold the per-file delete lock so the worker exits early without
+        # touching the database or file store.
+        lock_key = _user_file_delete_lock_key(user_file_id)
+        delete_lock = redis_client.lock(lock_key, timeout=10)
+        acquired = delete_lock.acquire(blocking=False)
+        assert acquired, "Should be able to acquire the delete lock for this test"
+
+        try:
+            process_single_user_file_delete.run(
+                user_file_id=user_file_id,
+                tenant_id=TEST_TENANT_ID,
+            )
+        finally:
+            if delete_lock.owned():
+                delete_lock.release()
+
+        assert not redis_client.exists(
+            guard_key
+        ), "Guard key should be deleted when the worker picks up the task"

backend/tests/external_dependency_unit/opensearch/test_opensearch_client.py

@@ -97,6 +97,23 @@ def _patch_hybrid_search_normalization_pipeline(
     )
 
 
+def _patch_opensearch_match_highlights_disabled(
+    monkeypatch: pytest.MonkeyPatch, disabled: bool
+) -> None:
+    """
+    Patches OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED wherever necessary for this
+    test file.
+    """
+    monkeypatch.setattr(
+        "onyx.configs.app_configs.OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED",
+        disabled,
+    )
+    monkeypatch.setattr(
+        "onyx.document_index.opensearch.search.OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED",
+        disabled,
+    )
+
+
 def _create_test_document_chunk(
     document_id: str,
     content: str,
@@ -805,6 +822,7 @@ class TestOpenSearchClient:
         """Tests all hybrid search configurations and pipelines."""
         # Precondition.
         _patch_global_tenant_state(monkeypatch, False)
+        _patch_opensearch_match_highlights_disabled(monkeypatch, False)
         tenant_state = TenantState(tenant_id=POSTGRES_DEFAULT_SCHEMA, multitenant=False)
         mappings = DocumentSchema.get_document_schema(
             vector_dimension=128, multitenant=tenant_state.multitenant
@@ -947,6 +965,7 @@ class TestOpenSearchClient:
         """
         # Precondition.
         _patch_global_tenant_state(monkeypatch, True)
+        _patch_opensearch_match_highlights_disabled(monkeypatch, False)
         tenant_x = TenantState(tenant_id="tenant-x", multitenant=True)
         tenant_y = TenantState(tenant_id="tenant-y", multitenant=True)
         mappings = DocumentSchema.get_document_schema(
@@ -1077,6 +1096,7 @@ class TestOpenSearchClient:
         """
         # Precondition.
         _patch_global_tenant_state(monkeypatch, True)
+        _patch_opensearch_match_highlights_disabled(monkeypatch, False)
         tenant_x = TenantState(tenant_id="tenant-x", multitenant=True)
         mappings = DocumentSchema.get_document_schema(
             vector_dimension=128, multitenant=tenant_x.multitenant

backend/tests/external_dependency_unit/tools/test_python_tool.py

@@ -1219,15 +1219,16 @@ def test_code_interpreter_receives_chat_files(
         finally:
             ci_mod.CodeInterpreterClient.__init__.__defaults__ = original_defaults
 
-    # Verify: file uploaded, code executed via streaming, staged file cleaned up
+    # Verify: file uploaded and code executed via streaming.
     assert len(mock_ci_server.get_requests(method="POST", path="/v1/files")) == 1
     assert (
         len(mock_ci_server.get_requests(method="POST", path="/v1/execute/stream")) == 1
     )
 
-    delete_requests = mock_ci_server.get_requests(method="DELETE")
-    assert len(delete_requests) == 1
-    assert delete_requests[0].path.startswith("/v1/files/")
+    # Staged input files are intentionally NOT deleted — PythonTool caches their
+    # file IDs across agent-loop iterations to avoid re-uploading on every call.
+    # The code interpreter cleans them up via its own TTL.
+    assert len(mock_ci_server.get_requests(method="DELETE")) == 0
 
     execute_body = mock_ci_server.get_requests(
         method="POST", path="/v1/execute/stream"

backend/tests/unit/onyx/db/test_projects_upload_task_expiry.py

@@ -0,0 +1,63 @@
+"""
+Unit test verifying that the upload API path sends tasks with expires=.
+
+The upload_files_to_user_files_with_indexing function must include expires=
+on every send_task call to prevent phantom task accumulation if the worker
+is down or slow.
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+from uuid import uuid4
+
+from onyx.configs.constants import CELERY_USER_FILE_PROCESSING_TASK_EXPIRES
+from onyx.configs.constants import OnyxCeleryQueues
+from onyx.configs.constants import OnyxCeleryTask
+from onyx.db.models import UserFile
+from onyx.db.projects import upload_files_to_user_files_with_indexing
+
+
+def _make_mock_user_file() -> MagicMock:
+    uf = MagicMock(spec=UserFile)
+    uf.id = str(uuid4())
+    return uf
+
+
+@patch("onyx.db.projects.get_current_tenant_id", return_value="test_tenant")
+@patch("onyx.db.projects.create_user_files")
+@patch(
+    "onyx.background.celery.versioned_apps.client.app",
+    new_callable=MagicMock,
+)
+def test_send_task_includes_expires(
+    mock_client_app: MagicMock,
+    mock_create: MagicMock,
+    mock_tenant: MagicMock,  # noqa: ARG001
+) -> None:
+    """Every send_task call from the upload path must include expires=."""
+    user_files = [_make_mock_user_file(), _make_mock_user_file()]
+    mock_create.return_value = MagicMock(
+        user_files=user_files,
+        rejected_files=[],
+        id_to_temp_id={},
+    )
+
+    mock_user = MagicMock()
+    mock_db_session = MagicMock()
+
+    upload_files_to_user_files_with_indexing(
+        files=[],
+        project_id=None,
+        user=mock_user,
+        temp_id_map=None,
+        db_session=mock_db_session,
+    )
+
+    assert mock_client_app.send_task.call_count == len(user_files)
+
+    for call in mock_client_app.send_task.call_args_list:
+        assert call.args[0] == OnyxCeleryTask.PROCESS_SINGLE_USER_FILE
+        assert call.kwargs.get("queue") == OnyxCeleryQueues.USER_FILE_PROCESSING
+        assert (
+            call.kwargs.get("expires") == CELERY_USER_FILE_PROCESSING_TASK_EXPIRES
+        ), "send_task must include expires= to prevent phantom task accumulation"

backend/tests/unit/onyx/file_processing/test_image_summarization_errors.py

@@ -0,0 +1,89 @@
+"""
+Unit tests for image summarization error handling.
+
+Verifies that:
+1. LLM errors produce actionable error messages (not base64 dumps)
+2. Unsupported MIME type logs include the magic bytes and size
+3. The ValueError raised on LLM failure preserves the original exception
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import pytest
+
+from onyx.file_processing.image_summarization import _summarize_image
+from onyx.file_processing.image_summarization import summarize_image_with_error_handling
+
+
+class TestSummarizeImageErrorMessage:
+    """_summarize_image must not dump base64 image data into error messages."""
+
+    def test_error_message_contains_exception_type_not_base64(self) -> None:
+        """The ValueError should contain the original exception info, not message payloads."""
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = RuntimeError("Connection timeout")
+
+        # A fake base64-encoded image string (should NOT appear in the error)
+        fake_encoded = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
+
+        with pytest.raises(ValueError, match="RuntimeError: Connection timeout"):
+            _summarize_image(fake_encoded, mock_llm, query="test")
+
+    def test_error_message_does_not_contain_base64(self) -> None:
+        """Ensure base64 data is never included in the error message."""
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = RuntimeError("API error")
+
+        fake_encoded = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image(fake_encoded, mock_llm)
+
+        error_str = str(exc_info.value)
+        assert "base64" not in error_str
+        assert "iVBOR" not in error_str
+
+    def test_original_exception_is_chained(self) -> None:
+        """The ValueError should chain the original exception via __cause__."""
+        mock_llm = MagicMock()
+        original = RuntimeError("upstream failure")
+        mock_llm.invoke.side_effect = original
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+        assert exc_info.value.__cause__ is original
+
+
+class TestUnsupportedMimeTypeLogging:
+    """summarize_image_with_error_handling should log useful info for unsupported formats."""
+
+    @patch(
+        "onyx.file_processing.image_summarization.summarize_image_pipeline",
+        side_effect=__import__(
+            "onyx.file_processing.image_summarization",
+            fromlist=["UnsupportedImageFormatError"],
+        ).UnsupportedImageFormatError("unsupported"),
+    )
+    def test_logs_magic_bytes_and_size(
+        self, mock_pipeline: MagicMock  # noqa: ARG002
+    ) -> None:
+        """The info log should include magic bytes hex and image size."""
+        mock_llm = MagicMock()
+        # TIFF magic bytes (not in the supported list)
+        image_data = b"\x49\x49\x2a\x00" + b"\x00" * 100
+
+        with patch("onyx.file_processing.image_summarization.logger") as mock_logger:
+            result = summarize_image_with_error_handling(
+                llm=mock_llm,
+                image_data=image_data,
+                context_name="test_image.tiff",
+            )
+
+        assert result is None
+        mock_logger.info.assert_called_once()
+        log_args = mock_logger.info.call_args
+        # Check the format string args contain magic bytes and size
+        assert "49492a00" in str(log_args)
+        assert "104" in str(log_args)  # 4 + 100 bytes

backend/tests/unit/onyx/file_processing/test_image_summarization_litellm_errors.py

@@ -0,0 +1,141 @@
+"""
+Unit tests verifying that LiteLLM error details are extracted and surfaced
+in image summarization error messages.
+
+When the LLM call fails, the error handler should include the status_code,
+llm_provider, and model from LiteLLM exceptions so operators can diagnose
+the root cause (rate limit, content filter, unsupported vision, etc.)
+without needing to dig through LiteLLM internals.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from onyx.file_processing.image_summarization import _summarize_image
+
+
+def _make_litellm_style_error(
+    *,
+    message: str = "API error",
+    status_code: int | None = None,
+    llm_provider: str | None = None,
+    model: str | None = None,
+) -> RuntimeError:
+    """Create an exception with LiteLLM-style attributes."""
+    exc = RuntimeError(message)
+    if status_code is not None:
+        exc.status_code = status_code  # type: ignore[attr-defined]
+    if llm_provider is not None:
+        exc.llm_provider = llm_provider  # type: ignore[attr-defined]
+    if model is not None:
+        exc.model = model  # type: ignore[attr-defined]
+    return exc
+
+
+class TestLiteLLMErrorExtraction:
+    """Verify that LiteLLM error attributes are included in the ValueError."""
+
+    def test_status_code_included(self) -> None:
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = _make_litellm_style_error(
+            message="Content filter triggered",
+            status_code=400,
+            llm_provider="azure",
+            model="gpt-4o",
+        )
+
+        with pytest.raises(ValueError, match="status_code=400"):
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+    def test_llm_provider_included(self) -> None:
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = _make_litellm_style_error(
+            message="Bad request",
+            status_code=400,
+            llm_provider="azure",
+        )
+
+        with pytest.raises(ValueError, match="llm_provider=azure"):
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+    def test_model_included(self) -> None:
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = _make_litellm_style_error(
+            message="Bad request",
+            model="gpt-4o",
+        )
+
+        with pytest.raises(ValueError, match="model=gpt-4o"):
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+    def test_all_fields_in_single_message(self) -> None:
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = _make_litellm_style_error(
+            message="Rate limit exceeded",
+            status_code=429,
+            llm_provider="azure",
+            model="gpt-4o",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+        msg = str(exc_info.value)
+        assert "status_code=429" in msg
+        assert "llm_provider=azure" in msg
+        assert "model=gpt-4o" in msg
+        assert "Rate limit exceeded" in msg
+
+    def test_plain_exception_without_litellm_attrs(self) -> None:
+        """Non-LiteLLM exceptions should still produce a useful message."""
+        mock_llm = MagicMock()
+        mock_llm.invoke.side_effect = ConnectionError("Connection refused")
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+        msg = str(exc_info.value)
+        assert "ConnectionError" in msg
+        assert "Connection refused" in msg
+        # Should not contain status_code/llm_provider/model
+        assert "status_code" not in msg
+        assert "llm_provider" not in msg
+
+    def test_no_base64_in_error(self) -> None:
+        """Error messages must not contain the full base64 image payload.
+
+        Some LiteLLM exceptions echo the request body (including base64 images)
+        in their message.  The truncation guard ensures the bulk of such a
+        payload is stripped from the re-raised ValueError.
+        """
+        mock_llm = MagicMock()
+        # Build a long base64-like payload that exceeds the 512-char truncation
+        fake_b64_payload = "iVBORw0KGgo" * 100  # ~1100 chars
+        fake_b64 = f"data:image/png;base64,{fake_b64_payload}"
+
+        mock_llm.invoke.side_effect = RuntimeError(
+            f"Request failed for payload: {fake_b64}"
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image(fake_b64, mock_llm)
+
+        msg = str(exc_info.value)
+        # The full payload must not appear (truncation should have kicked in)
+        assert fake_b64_payload not in msg
+        assert "truncated" in msg
+
+    def test_long_error_message_truncated(self) -> None:
+        """Exception messages longer than 512 chars are truncated."""
+        mock_llm = MagicMock()
+        long_msg = "x" * 1000
+        mock_llm.invoke.side_effect = RuntimeError(long_msg)
+
+        with pytest.raises(ValueError) as exc_info:
+            _summarize_image("data:image/png;base64,abc", mock_llm)
+
+        msg = str(exc_info.value)
+        assert "truncated" in msg
+        # The full 1000-char string should not appear
+        assert long_msg not in msg

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

@@ -0,0 +1,22 @@
+from typing import Any
+
+import pytest
+
+from onyx.db.enums import HookPoint
+from onyx.hooks.points.base import HookPointSpec
+
+
+def test_init_subclass_raises_for_missing_attrs() -> None:
+    with pytest.raises(TypeError, match="must define class attributes"):
+
+        class IncompleteSpec(HookPointSpec):
+            hook_point = HookPoint.QUERY_PROCESSING
+            # missing display_name, description, etc.
+
+            @property
+            def input_schema(self) -> dict[str, Any]:
+                return {}
+
+            @property
+            def output_schema(self) -> dict[str, Any]:
+                return {}

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

@@ -1,541 +0,0 @@
-"""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_models.py

@@ -0,0 +1,86 @@
+import pytest
+from pydantic import ValidationError
+
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.hooks.models import HookCreateRequest
+from onyx.hooks.models import HookUpdateRequest
+
+
+def test_hook_update_request_rejects_empty() -> None:
+    # No fields supplied at all
+    with pytest.raises(ValidationError, match="At least one field must be provided"):
+        HookUpdateRequest()
+
+
+def test_hook_update_request_rejects_null_name_when_only_field() -> None:
+    # Explicitly setting name=None is rejected as name cannot be cleared
+    with pytest.raises(ValidationError, match="name cannot be cleared"):
+        HookUpdateRequest(name=None)
+
+
+def test_hook_update_request_accepts_single_field() -> None:
+    req = HookUpdateRequest(name="new name")
+    assert req.name == "new name"
+
+
+def test_hook_update_request_accepts_partial_fields() -> None:
+    req = HookUpdateRequest(fail_strategy=HookFailStrategy.SOFT, timeout_seconds=10.0)
+    assert req.fail_strategy == HookFailStrategy.SOFT
+    assert req.timeout_seconds == 10.0
+    assert req.name is None
+
+
+def test_hook_update_request_rejects_null_name() -> None:
+    with pytest.raises(ValidationError, match="name cannot be cleared"):
+        HookUpdateRequest(name=None, fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_update_request_rejects_empty_name() -> None:
+    with pytest.raises(ValidationError, match="name cannot be cleared"):
+        HookUpdateRequest(name="", fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_update_request_rejects_null_endpoint_url() -> None:
+    with pytest.raises(ValidationError, match="endpoint_url cannot be cleared"):
+        HookUpdateRequest(endpoint_url=None, fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_update_request_rejects_empty_endpoint_url() -> None:
+    with pytest.raises(ValidationError, match="endpoint_url cannot be cleared"):
+        HookUpdateRequest(endpoint_url="", fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_update_request_allows_null_api_key() -> None:
+    # api_key=null is valid — means "clear the api key"
+    req = HookUpdateRequest(api_key=None)
+    assert req.api_key is None
+    assert "api_key" in req.model_fields_set
+
+
+def test_hook_update_request_rejects_whitespace_name() -> None:
+    with pytest.raises(ValidationError, match="name cannot be cleared"):
+        HookUpdateRequest(name="   ", fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_update_request_rejects_whitespace_endpoint_url() -> None:
+    with pytest.raises(ValidationError, match="endpoint_url cannot be cleared"):
+        HookUpdateRequest(endpoint_url="   ", fail_strategy=HookFailStrategy.SOFT)
+
+
+def test_hook_create_request_rejects_whitespace_name() -> None:
+    with pytest.raises(ValidationError, match="whitespace-only"):
+        HookCreateRequest(
+            name="   ",
+            hook_point=HookPoint.QUERY_PROCESSING,
+            endpoint_url="https://example.com/hook",
+        )
+
+
+def test_hook_create_request_rejects_whitespace_endpoint_url() -> None:
+    with pytest.raises(ValidationError, match="whitespace-only"):
+        HookCreateRequest(
+            name="my hook",
+            hook_point=HookPoint.QUERY_PROCESSING,
+            endpoint_url="   ",
+        )

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

@@ -0,0 +1,60 @@
+from onyx.db.enums import HookFailStrategy
+from onyx.db.enums import HookPoint
+from onyx.hooks.points.query_processing import QueryProcessingSpec
+
+
+def test_hook_point_is_query_processing() -> None:
+    assert QueryProcessingSpec().hook_point == HookPoint.QUERY_PROCESSING
+
+
+def test_default_fail_strategy_is_hard() -> None:
+    assert QueryProcessingSpec().default_fail_strategy == HookFailStrategy.HARD
+
+
+def test_default_timeout_seconds() -> None:
+    # User is actively waiting — 5s is the documented contract for this hook point
+    assert QueryProcessingSpec().default_timeout_seconds == 5.0
+
+
+def test_input_schema_required_fields() -> None:
+    schema = QueryProcessingSpec().input_schema
+    assert schema["type"] == "object"
+    required = schema["required"]
+    assert "query" in required
+    assert "user_email" in required
+    assert "chat_session_id" in required
+
+
+def test_input_schema_chat_session_id_is_string() -> None:
+    props = QueryProcessingSpec().input_schema["properties"]
+    assert props["chat_session_id"]["type"] == "string"
+
+
+def test_input_schema_query_is_string() -> None:
+    props = QueryProcessingSpec().input_schema["properties"]
+    assert props["query"]["type"] == "string"
+
+
+def test_input_schema_user_email_is_nullable() -> None:
+    props = QueryProcessingSpec().input_schema["properties"]
+    assert "null" in props["user_email"]["type"]
+
+
+def test_output_schema_query_is_required() -> None:
+    schema = QueryProcessingSpec().output_schema
+    assert "query" in schema["required"]
+
+
+def test_output_schema_query_is_nullable() -> None:
+    # null means "reject the query"
+    props = QueryProcessingSpec().output_schema["properties"]
+    assert "null" in props["query"]["type"]
+
+
+def test_output_schema_rejection_message_is_optional() -> None:
+    schema = QueryProcessingSpec().output_schema
+    assert "rejection_message" not in schema.get("required", [])
+
+
+def test_input_schema_no_additional_properties() -> None:
+    assert QueryProcessingSpec().input_schema.get("additionalProperties") is False

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

@@ -0,0 +1,47 @@
+import pytest
+
+from onyx.db.enums import HookPoint
+from onyx.hooks import registry as registry_module
+from onyx.hooks.registry import get_all_specs
+from onyx.hooks.registry import get_hook_point_spec
+from onyx.hooks.registry import validate_registry
+
+
+def test_registry_covers_all_hook_points() -> None:
+    """Every HookPoint enum member must have a registered spec."""
+    assert {s.hook_point for s in get_all_specs()} == set(
+        HookPoint
+    ), f"Missing specs for: {set(HookPoint) - {s.hook_point for s in get_all_specs()}}"
+
+
+def test_get_hook_point_spec_returns_correct_spec() -> None:
+    for hook_point in HookPoint:
+        spec = get_hook_point_spec(hook_point)
+        assert spec.hook_point == hook_point
+
+
+def test_get_all_specs_returns_all() -> None:
+    specs = get_all_specs()
+    assert len(specs) == len(HookPoint)
+    assert {s.hook_point for s in specs} == set(HookPoint)
+
+
+def test_get_hook_point_spec_raises_for_unregistered(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """get_hook_point_spec raises ValueError when a hook point has no spec."""
+    monkeypatch.setattr(registry_module, "_REGISTRY", {})
+    with pytest.raises(ValueError, match="No spec registered for hook point"):
+        get_hook_point_spec(HookPoint.QUERY_PROCESSING)
+
+
+def test_validate_registry_passes() -> None:
+    validate_registry()  # should not raise with the real registry
+
+
+def test_validate_registry_raises_for_incomplete(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(registry_module, "_REGISTRY", {})
+    with pytest.raises(RuntimeError, match="Hook point\\(s\\) have no registered spec"):
+        validate_registry()

backend/tests/unit/onyx/llm/test_vision_model_selection_logging.py

@@ -0,0 +1,130 @@
+"""
+Unit tests for vision model selection logging in get_default_llm_with_vision.
+
+Verifies that operators get clear feedback about:
+1. Which vision model was selected and why
+2. When the default vision model doesn't support image input
+3. When no vision-capable model exists at all
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+from onyx.llm.factory import get_default_llm_with_vision
+
+
+_FACTORY = "onyx.llm.factory"
+
+
+def _make_mock_model(
+    *,
+    name: str = "gpt-4o",
+    provider: str = "openai",
+    provider_id: int = 1,
+    flow_types: list[str] | None = None,
+) -> MagicMock:
+    model = MagicMock()
+    model.name = name
+    model.llm_provider_id = provider_id
+    model.llm_provider.provider = provider
+    model.llm_model_flow_types = flow_types or []
+    return model
+
+
+@patch(f"{_FACTORY}.get_session_with_current_tenant")
+@patch(f"{_FACTORY}.fetch_default_vision_model")
+@patch(f"{_FACTORY}.model_supports_image_input", return_value=True)
+@patch(f"{_FACTORY}.llm_from_provider")
+@patch(f"{_FACTORY}.LLMProviderView")
+@patch(f"{_FACTORY}.logger")
+def test_logs_when_using_default_vision_model(
+    mock_logger: MagicMock,
+    mock_provider_view: MagicMock,  # noqa: ARG001
+    mock_llm_from: MagicMock,  # noqa: ARG001
+    mock_supports: MagicMock,  # noqa: ARG001
+    mock_fetch_default: MagicMock,
+    mock_session: MagicMock,  # noqa: ARG001
+) -> None:
+    mock_fetch_default.return_value = _make_mock_model(name="gpt-4o", provider="azure")
+
+    get_default_llm_with_vision()
+
+    mock_logger.info.assert_called_once()
+    log_msg = mock_logger.info.call_args[0][0]
+    assert "default vision model" in log_msg.lower()
+
+
+@patch(f"{_FACTORY}.get_session_with_current_tenant")
+@patch(f"{_FACTORY}.fetch_default_vision_model")
+@patch(f"{_FACTORY}.model_supports_image_input", return_value=False)
+@patch(f"{_FACTORY}.fetch_existing_models", return_value=[])
+@patch(f"{_FACTORY}.logger")
+def test_warns_when_default_model_lacks_vision(
+    mock_logger: MagicMock,
+    mock_fetch_models: MagicMock,  # noqa: ARG001
+    mock_supports: MagicMock,  # noqa: ARG001
+    mock_fetch_default: MagicMock,
+    mock_session: MagicMock,  # noqa: ARG001
+) -> None:
+    mock_fetch_default.return_value = _make_mock_model(
+        name="text-only-model", provider="azure"
+    )
+
+    result = get_default_llm_with_vision()
+
+    assert result is None
+    # Should have warned about the default model not supporting vision
+    warning_calls = [
+        call
+        for call in mock_logger.warning.call_args_list
+        if "does not support" in str(call)
+    ]
+    assert len(warning_calls) >= 1
+
+
+@patch(f"{_FACTORY}.get_session_with_current_tenant")
+@patch(f"{_FACTORY}.fetch_default_vision_model", return_value=None)
+@patch(f"{_FACTORY}.fetch_existing_models", return_value=[])
+@patch(f"{_FACTORY}.logger")
+def test_warns_when_no_models_exist(
+    mock_logger: MagicMock,
+    mock_fetch_models: MagicMock,  # noqa: ARG001
+    mock_fetch_default: MagicMock,  # noqa: ARG001
+    mock_session: MagicMock,  # noqa: ARG001
+) -> None:
+    result = get_default_llm_with_vision()
+
+    assert result is None
+    mock_logger.warning.assert_called_once()
+    log_msg = mock_logger.warning.call_args[0][0]
+    assert "no llm models" in log_msg.lower()
+
+
+@patch(f"{_FACTORY}.get_session_with_current_tenant")
+@patch(f"{_FACTORY}.fetch_default_vision_model", return_value=None)
+@patch(f"{_FACTORY}.fetch_existing_models")
+@patch(f"{_FACTORY}.model_supports_image_input", return_value=False)
+@patch(f"{_FACTORY}.LLMProviderView")
+@patch(f"{_FACTORY}.logger")
+def test_warns_when_no_model_supports_vision(
+    mock_logger: MagicMock,
+    mock_provider_view: MagicMock,  # noqa: ARG001
+    mock_supports: MagicMock,  # noqa: ARG001
+    mock_fetch_models: MagicMock,
+    mock_fetch_default: MagicMock,  # noqa: ARG001
+    mock_session: MagicMock,  # noqa: ARG001
+) -> None:
+    mock_fetch_models.return_value = [
+        _make_mock_model(name="text-model-1", provider="openai"),
+        _make_mock_model(name="text-model-2", provider="azure", provider_id=2),
+    ]
+
+    result = get_default_llm_with_vision()
+
+    assert result is None
+    warning_calls = [
+        call
+        for call in mock_logger.warning.call_args_list
+        if "no vision-capable model" in str(call).lower()
+    ]
+    assert len(warning_calls) == 1

backend/tests/unit/onyx/tools/tool_implementations/python/test_python_tool_upload_cache.py

@@ -0,0 +1,208 @@
+"""Unit tests for PythonTool file-upload caching.
+
+Verifies that PythonTool reuses code-interpreter file IDs across multiple
+run() calls within the same session instead of re-uploading identical content
+on every agent loop iteration.
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+from onyx.tools.models import ChatFile
+from onyx.tools.models import PythonToolOverrideKwargs
+from onyx.tools.tool_implementations.python.code_interpreter_client import (
+    StreamResultEvent,
+)
+from onyx.tools.tool_implementations.python.python_tool import PythonTool
+
+TOOL_MODULE = "onyx.tools.tool_implementations.python.python_tool"
+
+
+def _make_stream_result() -> StreamResultEvent:
+    return StreamResultEvent(
+        exit_code=0,
+        timed_out=False,
+        duration_ms=10,
+        files=[],
+    )
+
+
+def _make_tool() -> PythonTool:
+    emitter = MagicMock()
+    return PythonTool(tool_id=1, emitter=emitter)
+
+
+def _make_override(files: list[ChatFile]) -> PythonToolOverrideKwargs:
+    return PythonToolOverrideKwargs(chat_files=files)
+
+
+def _run_tool(tool: PythonTool, mock_client: MagicMock, files: list[ChatFile]) -> None:
+    """Call tool.run() with a mocked CodeInterpreterClient context manager."""
+    from onyx.server.query_and_chat.placement import Placement
+
+    mock_client.execute_streaming.return_value = iter([_make_stream_result()])
+
+    ctx = MagicMock()
+    ctx.__enter__ = MagicMock(return_value=mock_client)
+    ctx.__exit__ = MagicMock(return_value=False)
+
+    placement = Placement(turn_index=0, tab_index=0)
+    override = _make_override(files)
+
+    with patch(f"{TOOL_MODULE}.CodeInterpreterClient", return_value=ctx):
+        tool.run(placement=placement, override_kwargs=override, code="print('hi')")
+
+
+# ---------------------------------------------------------------------------
+# Cache hit: same content uploaded in a second call reuses the file_id
+# ---------------------------------------------------------------------------
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_same_file_uploaded_only_once_across_two_runs() -> None:
+    tool = _make_tool()
+    client = MagicMock()
+    client.upload_file.return_value = "file-id-abc"
+
+    pptx_content = b"fake pptx bytes"
+    files = [ChatFile(filename="report.pptx", content=pptx_content)]
+
+    _run_tool(tool, client, files)
+    _run_tool(tool, client, files)
+
+    # upload_file should only have been called once across both runs
+    client.upload_file.assert_called_once_with(pptx_content, "report.pptx")
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_cached_file_id_is_staged_on_second_run() -> None:
+    tool = _make_tool()
+    client = MagicMock()
+    client.upload_file.return_value = "file-id-abc"
+
+    files = [ChatFile(filename="data.pptx", content=b"content")]
+
+    _run_tool(tool, client, files)
+
+    # On the second run, execute_streaming should still receive the file
+    client.execute_streaming.return_value = iter([_make_stream_result()])
+    ctx = MagicMock()
+    ctx.__enter__ = MagicMock(return_value=client)
+    ctx.__exit__ = MagicMock(return_value=False)
+
+    from onyx.server.query_and_chat.placement import Placement
+
+    placement = Placement(turn_index=1, tab_index=0)
+    with patch(f"{TOOL_MODULE}.CodeInterpreterClient", return_value=ctx):
+        tool.run(
+            placement=placement,
+            override_kwargs=_make_override(files),
+            code="print('hi')",
+        )
+
+    # The second execute_streaming call should include the file
+    _, kwargs = client.execute_streaming.call_args
+    staged_files = kwargs.get("files") or []
+    assert any(f["file_id"] == "file-id-abc" for f in staged_files)
+
+
+# ---------------------------------------------------------------------------
+# Cache miss: different content triggers a new upload
+# ---------------------------------------------------------------------------
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_different_file_content_uploaded_separately() -> None:
+    tool = _make_tool()
+    client = MagicMock()
+    client.upload_file.side_effect = ["file-id-v1", "file-id-v2"]
+
+    file_v1 = ChatFile(filename="report.pptx", content=b"version 1")
+    file_v2 = ChatFile(filename="report.pptx", content=b"version 2")
+
+    _run_tool(tool, client, [file_v1])
+    _run_tool(tool, client, [file_v2])
+
+    assert client.upload_file.call_count == 2
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_multiple_distinct_files_each_uploaded_once() -> None:
+    tool = _make_tool()
+    client = MagicMock()
+    client.upload_file.side_effect = ["id-a", "id-b"]
+
+    files = [
+        ChatFile(filename="a.pptx", content=b"aaa"),
+        ChatFile(filename="b.xlsx", content=b"bbb"),
+    ]
+
+    _run_tool(tool, client, files)
+    _run_tool(tool, client, files)
+
+    # Two distinct files — each uploaded exactly once
+    assert client.upload_file.call_count == 2
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_same_content_different_filename_uploaded_separately() -> None:
+    # Identical bytes but different names must each get their own upload slot
+    # so both files appear under their respective paths in the workspace.
+    tool = _make_tool()
+    client = MagicMock()
+    client.upload_file.side_effect = ["id-v1", "id-v2"]
+
+    same_bytes = b"shared content"
+    files = [
+        ChatFile(filename="report_v1.csv", content=same_bytes),
+        ChatFile(filename="report_v2.csv", content=same_bytes),
+    ]
+
+    _run_tool(tool, client, files)
+
+    assert client.upload_file.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# No cross-instance sharing: a fresh PythonTool re-uploads everything
+# ---------------------------------------------------------------------------
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_new_tool_instance_re_uploads_file() -> None:
+    client = MagicMock()
+    client.upload_file.side_effect = ["id-session-1", "id-session-2"]
+
+    files = [ChatFile(filename="deck.pptx", content=b"slide data")]
+
+    tool_session_1 = _make_tool()
+    _run_tool(tool_session_1, client, files)
+
+    tool_session_2 = _make_tool()
+    _run_tool(tool_session_2, client, files)
+
+    # Different instances — each uploads independently
+    assert client.upload_file.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# Upload failure: failed upload is not cached, retried next run
+# ---------------------------------------------------------------------------
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://fake:8000")
+def test_upload_failure_not_cached() -> None:
+    tool = _make_tool()
+    client = MagicMock()
+    # First call raises, second succeeds
+    client.upload_file.side_effect = [Exception("network error"), "file-id-ok"]
+
+    files = [ChatFile(filename="slides.pptx", content=b"data")]
+
+    # First run — upload fails, file is skipped but not cached
+    _run_tool(tool, client, files)
+
+    # Second run — should attempt upload again
+    _run_tool(tool, client, files)
+
+    assert client.upload_file.call_count == 2

web/lib/opal/src/components/buttons/button/components.tsx

@@ -1,4 +1,3 @@
-import "@opal/components/buttons/button/styles.css";
 import "@opal/components/tooltip.css";
 import { Interactive, type InteractiveStatelessProps } from "@opal/core";
 import type { ContainerSizeVariants, ExtremaSizeVariants } from "@opal/types";
@@ -67,7 +66,7 @@ function Button({
   const labelEl = children ? (
     <span
       className={cn(
-        "opal-button-label",
+        "whitespace-nowrap",
         isLarge ? "font-main-ui-body " : "font-secondary-body",
         responsiveHideText && "hidden md:inline"
       )}
@@ -87,7 +86,7 @@ function Button({
           isLarge ? "default" : size === "2xs" ? "mini" : "compact"
         }
       >
-        <div className={cn("opal-button interactive-foreground")}>
+        <div className="flex flex-row items-center gap-1 interactive-foreground">
           {iconWrapper(Icon, size, !!children)}
 
           {labelEl}

web/lib/opal/src/components/buttons/button/styles.css

@@ -1,9 +0,0 @@
-/* Button — layout only; colors handled by Interactive.Stateless */
-
-.opal-button {
-  @apply flex flex-row items-center gap-1;
-}
-
-.opal-button-label {
-  @apply whitespace-nowrap;
-}

web/lib/opal/src/components/buttons/open-button/components.tsx

@@ -118,7 +118,7 @@ function OpenButton({
   const labelEl = children ? (
     <span
       className={cn(
-        "opal-button-label whitespace-nowrap",
+        "whitespace-nowrap",
         isLarge ? "font-main-ui-body" : "font-secondary-body"
       )}
     >
@@ -143,7 +143,7 @@ function OpenButton({
       >
         <div
           className={cn(
-            "opal-button interactive-foreground flex flex-row items-center",
+            "interactive-foreground flex flex-row items-center",
             justifyContent === "between" ? "w-full justify-between" : "gap-1",
             foldable &&
               justifyContent !== "between" &&

web/lib/opal/src/components/index.ts

@@ -52,3 +52,8 @@ export {
   type PaginationProps,
   type PaginationSize,
 } from "@opal/components/pagination/components";
+
+/* Table */
+export { Table } from "@opal/components/table/components";
+export { createTableColumns } from "@opal/components/table/columns";
+export type { DataTableProps } from "@opal/components/table/components";

web/lib/opal/src/components/table/ActionsContainer.tsx

@@ -1,5 +1,5 @@
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 
 interface ActionsContainerProps {
   type: "head" | "cell";

web/lib/opal/src/components/table/ColumnSortabilityPopover.tsx

@@ -7,11 +7,10 @@ import {
   type RowData,
   type SortingState,
 } from "@tanstack/react-table";
-import { Button } from "@opal/components";
+import { Button, LineItemButton } from "@opal/components";
 import { SvgArrowUpDown, SvgSortOrder, SvgCheck } from "@opal/icons";
 import Popover from "@/refresh-components/Popover";
 import Divider from "@/refresh-components/Divider";
-import LineItem from "@/refresh-components/buttons/LineItem";
 import Text from "@/refresh-components/texts/Text";
 
 // ---------------------------------------------------------------------------
@@ -21,7 +20,7 @@ import Text from "@/refresh-components/texts/Text";
 interface SortingPopoverProps<TData extends RowData = RowData> {
   table: Table<TData>;
   sorting: SortingState;
-  size?: "regular" | "small";
+  size?: "md" | "lg";
   footerText?: string;
   ascendingLabel?: string;
   descendingLabel?: string;
@@ -30,7 +29,7 @@ interface SortingPopoverProps<TData extends RowData = RowData> {
 function SortingPopover<TData extends RowData>({
   table,
   sorting,
-  size = "regular",
+  size = "lg",
   footerText,
   ascendingLabel = "Ascending",
   descendingLabel = "Descending",
@@ -48,8 +47,8 @@ function SortingPopover<TData extends RowData>({
         <Button
           icon={currentSort === null ? SvgArrowUpDown : SvgSortOrder}
           interaction={open ? "hover" : "rest"}
-          size={size === "small" ? "sm" : "md"}
-          prominence="internal"
+          size={size === "md" ? "sm" : "md"}
+          prominence="tertiary"
           tooltip="Sort"
         />
       </Popover.Trigger>
@@ -68,18 +67,20 @@ function SortingPopover<TData extends RowData>({
         >
           <Divider showTitle text="Sort by" />
 
-          <LineItem
-            selected={currentSort === null}
-            emphasized
+          <LineItemButton
+            selectVariant="select-heavy"
+            state={currentSort === null ? "selected" : "empty"}
+            title="Manual Ordering"
+            sizePreset="main-ui"
             rightChildren={
-              currentSort === null ? <SvgCheck size={16} /> : undefined
+              currentSort === null ? (
+                <SvgCheck size={16} className="text-action-link-05" />
+              ) : undefined
             }
             onClick={() => {
               table.resetSorting();
             }}
-          >
-            Manual Ordering
-          </LineItem>
+          />
 
           {sortableColumns.map((column) => {
             const isSorted = currentSort?.id === column.id;
@@ -89,11 +90,17 @@ function SortingPopover<TData extends RowData>({
                 : column.id;
 
             return (
-              <LineItem
+              <LineItemButton
                 key={column.id}
-                selected={isSorted}
-                emphasized
-                rightChildren={isSorted ? <SvgCheck size={16} /> : undefined}
+                selectVariant="select-heavy"
+                state={isSorted ? "selected" : "empty"}
+                title={label}
+                sizePreset="main-ui"
+                rightChildren={
+                  isSorted ? (
+                    <SvgCheck size={16} className="text-action-link-05" />
+                  ) : undefined
+                }
                 onClick={() => {
                   if (isSorted) {
                     table.resetSorting();
@@ -101,9 +108,7 @@ function SortingPopover<TData extends RowData>({
                   }
                   column.toggleSorting(false);
                 }}
-              >
-                {label}
-              </LineItem>
+              />
             );
           })}
 
@@ -111,31 +116,35 @@ function SortingPopover<TData extends RowData>({
             <>
               <Divider showTitle text="Sorting Order" />
 
-              <LineItem
-                selected={!currentSort.desc}
-                emphasized
+              <LineItemButton
+                selectVariant="select-heavy"
+                state={!currentSort.desc ? "selected" : "empty"}
+                title={ascendingLabel}
+                sizePreset="main-ui"
                 rightChildren={
-                  !currentSort.desc ? <SvgCheck size={16} /> : undefined
+                  !currentSort.desc ? (
+                    <SvgCheck size={16} className="text-action-link-05" />
+                  ) : undefined
                 }
                 onClick={() => {
                   table.setSorting([{ id: currentSort.id, desc: false }]);
                 }}
-              >
-                {ascendingLabel}
-              </LineItem>
+              />
 
-              <LineItem
-                selected={currentSort.desc}
-                emphasized
+              <LineItemButton
+                selectVariant="select-heavy"
+                state={currentSort.desc ? "selected" : "empty"}
+                title={descendingLabel}
+                sizePreset="main-ui"
                 rightChildren={
-                  currentSort.desc ? <SvgCheck size={16} /> : undefined
+                  currentSort.desc ? (
+                    <SvgCheck size={16} className="text-action-link-05" />
+                  ) : undefined
                 }
                 onClick={() => {
                   table.setSorting([{ id: currentSort.id, desc: true }]);
                 }}
-              >
-                {descendingLabel}
-              </LineItem>
+              />
             </>
           )}
         </Popover.Menu>
@@ -149,7 +158,7 @@ function SortingPopover<TData extends RowData>({
 // ---------------------------------------------------------------------------
 
 interface CreateSortingColumnOptions {
-  size?: "regular" | "small";
+  size?: "md" | "lg";
   footerText?: string;
   ascendingLabel?: string;
   descendingLabel?: string;

web/lib/opal/src/components/table/ColumnVisibilityPopover.tsx

@@ -7,10 +7,9 @@ import {
   type RowData,
   type VisibilityState,
 } from "@tanstack/react-table";
-import { Button } from "@opal/components";
+import { Button, LineItemButton, Tag } from "@opal/components";
 import { SvgColumn, SvgCheck } from "@opal/icons";
 import Popover from "@/refresh-components/Popover";
-import LineItem from "@/refresh-components/buttons/LineItem";
 import Divider from "@/refresh-components/Divider";
 
 // ---------------------------------------------------------------------------
@@ -20,18 +19,20 @@ import Divider from "@/refresh-components/Divider";
 interface ColumnVisibilityPopoverProps<TData extends RowData = RowData> {
   table: Table<TData>;
   columnVisibility: VisibilityState;
-  size?: "regular" | "small";
+  size?: "md" | "lg";
 }
 
 function ColumnVisibilityPopover<TData extends RowData>({
   table,
   columnVisibility,
-  size = "regular",
+  size = "lg",
 }: ColumnVisibilityPopoverProps<TData>) {
   const [open, setOpen] = useState(false);
-  const hideableColumns = table
+
+  // User-defined columns only (exclude internal qualifier/actions)
+  const dataColumns = table
     .getAllLeafColumns()
-    .filter((col) => col.getCanHide());
+    .filter((col) => !col.id.startsWith("__") && col.id !== "qualifier");
 
   return (
     <Popover open={open} onOpenChange={setOpen}>
@@ -39,8 +40,8 @@ function ColumnVisibilityPopover<TData extends RowData>({
         <Button
           icon={SvgColumn}
           interaction={open ? "hover" : "rest"}
-          size={size === "small" ? "sm" : "md"}
-          prominence="internal"
+          size={size === "md" ? "sm" : "md"}
+          prominence="tertiary"
           tooltip="Columns"
         />
       </Popover.Trigger>
@@ -48,7 +49,8 @@ function ColumnVisibilityPopover<TData extends RowData>({
       <Popover.Content width="lg" align="end" side="bottom">
         <Divider showTitle text="Shown Columns" />
         <Popover.Menu>
-          {hideableColumns.map((column) => {
+          {dataColumns.map((column) => {
+            const canHide = column.getCanHide();
             const isVisible = columnVisibility[column.id] !== false;
             const label =
               typeof column.columnDef.header === "string"
@@ -56,17 +58,23 @@ function ColumnVisibilityPopover<TData extends RowData>({
                 : column.id;
 
             return (
-              <LineItem
+              <LineItemButton
                 key={column.id}
-                selected={isVisible}
-                emphasized
-                rightChildren={isVisible ? <SvgCheck size={16} /> : undefined}
-                onClick={() => {
-                  column.toggleVisibility();
-                }}
-              >
-                {label}
-              </LineItem>
+                selectVariant="select-heavy"
+                state={isVisible ? "selected" : "empty"}
+                title={label}
+                sizePreset="main-ui"
+                rightChildren={
+                  !canHide ? (
+                    <div className="flex items-center">
+                      <Tag title="Always Shown" color="blue" />
+                    </div>
+                  ) : isVisible ? (
+                    <SvgCheck size={16} className="text-action-link-05" />
+                  ) : undefined
+                }
+                onClick={canHide ? () => column.toggleVisibility() : undefined}
+              />
             );
           })}
         </Popover.Menu>
@@ -80,7 +88,7 @@ function ColumnVisibilityPopover<TData extends RowData>({
 // ---------------------------------------------------------------------------
 
 interface CreateColumnVisibilityColumnOptions {
-  size?: "regular" | "small";
+  size?: "md" | "lg";
 }
 
 function createColumnVisibilityColumn<TData>(

web/lib/opal/src/components/table/DragOverlayRow.tsx

@@ -1,18 +1,17 @@
 import { memo } from "react";
 import { type Row, flexRender } from "@tanstack/react-table";
-import TableRow from "@/refresh-components/table/TableRow";
-import TableCell from "@/refresh-components/table/TableCell";
-import QualifierContainer from "@/refresh-components/table/QualifierContainer";
-import TableQualifier from "@/refresh-components/table/TableQualifier";
-import ActionsContainer from "@/refresh-components/table/ActionsContainer";
+import TableRow from "@opal/components/table/TableRow";
+import TableCell from "@opal/components/table/TableCell";
+import QualifierContainer from "@opal/components/table/QualifierContainer";
+import TableQualifier from "@opal/components/table/TableQualifier";
+import ActionsContainer from "@opal/components/table/ActionsContainer";
 import type {
   OnyxColumnDef,
   OnyxQualifierColumn,
-} from "@/refresh-components/table/types";
+} from "@opal/components/table/types";
 
 interface DragOverlayRowProps<TData> {
   row: Row<TData>;
-  variant?: "table" | "list";
   columnWidths?: Record<string, number>;
   columnKindMap?: Map<string, OnyxColumnDef<TData>>;
   qualifierColumn?: OnyxQualifierColumn<TData> | null;
@@ -21,7 +20,6 @@ interface DragOverlayRowProps<TData> {
 
 function DragOverlayRowInner<TData>({
   row,
-  variant,
   columnWidths,
   columnKindMap,
   qualifierColumn,
@@ -50,7 +48,7 @@ function DragOverlayRowInner<TData>({
         </colgroup>
       )}
       <tbody>
-        <TableRow variant={variant} selected={row.getIsSelected()}>
+        <TableRow selected={row.getIsSelected()}>
           {row.getVisibleCells().map((cell) => {
             const colDef = columnKindMap?.get(cell.column.id);
 

web/lib/opal/src/components/table/Footer.tsx

@@ -1,10 +1,10 @@
 "use client";
 
-import { cn } from "@/lib/utils";
-import { Button, Pagination } from "@opal/components";
+import { cn } from "@opal/utils";
+import { Button, Pagination, SelectButton } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import { SvgEye, SvgXCircle } from "@opal/icons";
 import type { ReactNode } from "react";
 
@@ -27,9 +27,11 @@ interface FooterSelectionModeProps {
   selectionState: SelectionState;
   /** Number of currently selected items. */
   selectedCount: number;
-  /** If provided, renders a "View" icon button when items are selected. */
+  /** Toggle view-filter on/off. */
   onView?: () => void;
-  /** If provided, renders a "Clear" icon button when items are selected. */
+  /** Whether the view-filter is currently active. */
+  isViewingSelected?: boolean;
+  /** Clears all selections. */
   onClear?: () => void;
   /** Number of items displayed per page. */
   pageSize: number;
@@ -41,7 +43,9 @@ interface FooterSelectionModeProps {
   totalPages: number;
   /** Called when the user navigates to a different page. */
   onPageChange: (page: number) => void;
-  /** Controls overall footer sizing. `"regular"` (default) or `"small"`. */
+  /** Unit label for count pagination. @default "items" */
+  units?: string;
+  /** Controls overall footer sizing. `"lg"` (default) or `"md"`. */
   size?: TableSize;
   className?: string;
 }
@@ -67,6 +71,8 @@ interface FooterSummaryModeProps {
   onPageChange: (page: number) => void;
   /** Optional extra element rendered after the summary text (e.g. a download icon). */
   leftExtra?: ReactNode;
+  /** Unit label for the summary text, e.g. "users". */
+  units?: string;
   className?: string;
 }
 
@@ -84,9 +90,10 @@ export type FooterProps = FooterSelectionModeProps | FooterSummaryModeProps;
 function getSelectionMessage(
   state: SelectionState,
   multi: boolean,
-  count: number
+  count: number,
+  isViewingSelected: boolean
 ): string {
-  if (state === "none") {
+  if (state === "none" && !isViewingSelected) {
     return multi ? "Select items to continue" : "Select an item to continue";
   }
   if (!multi) return "Item selected";
@@ -100,7 +107,7 @@ function getSelectionMessage(
  */
 export default function Footer(props: FooterProps) {
   const resolvedSize = useTableSize();
-  const isSmall = resolvedSize === "small";
+  const isSmall = resolvedSize === "md";
   return (
     <div
       className={cn(
@@ -118,6 +125,7 @@ export default function Footer(props: FooterProps) {
             multiSelect={props.multiSelect}
             selectedCount={props.selectedCount}
             onView={props.onView}
+            isViewingSelected={props.isViewingSelected}
             onClear={props.onClear}
             isSmall={isSmall}
           />
@@ -127,6 +135,7 @@ export default function Footer(props: FooterProps) {
               rangeStart={props.rangeStart}
               rangeEnd={props.rangeEnd}
               totalItems={props.totalItems}
+              units={props.units}
               isSmall={isSmall}
             />
             {props.leftExtra}
@@ -144,7 +153,7 @@ export default function Footer(props: FooterProps) {
             currentPage={props.currentPage}
             totalPages={props.totalPages}
             onChange={props.onPageChange}
-            units="items"
+            units={props.units}
             size={isSmall ? "sm" : "md"}
           />
         ) : (
@@ -169,6 +178,7 @@ interface SelectionLeftProps {
   multiSelect: boolean;
   selectedCount: number;
   onView?: () => void;
+  isViewingSelected?: boolean;
   onClear?: () => void;
   isSmall: boolean;
 }
@@ -178,15 +188,19 @@ function SelectionLeft({
   multiSelect,
   selectedCount,
   onView,
+  isViewingSelected = false,
   onClear,
   isSmall,
 }: SelectionLeftProps) {
   const message = getSelectionMessage(
     selectionState,
     multiSelect,
-    selectedCount
+    selectedCount,
+    isViewingSelected
   );
   const hasSelection = selectionState !== "none";
+  // Show buttons when items are selected OR when the view filter is active
+  const showActions = hasSelection || isViewingSelected;
 
   return (
     <div className="flex flex-row gap-1 items-center justify-center w-fit flex-shrink-0 h-fit px-1">
@@ -204,22 +218,22 @@ function SelectionLeft({
         </Text>
       )}
 
-      {hasSelection && (
+      {showActions && (
         <div className="flex flex-row items-center w-fit flex-shrink-0 h-fit">
           {onView && (
-            <Button
+            <SelectButton
               icon={SvgEye}
+              state={isViewingSelected ? "selected" : "empty"}
               onClick={onView}
-              tooltip="View"
+              tooltip="View selected"
               size={isSmall ? "sm" : "md"}
-              prominence="tertiary"
             />
           )}
           {onClear && (
             <Button
               icon={SvgXCircle}
               onClick={onClear}
-              tooltip="Clear selection"
+              tooltip="Deselect all"
               size={isSmall ? "sm" : "md"}
               prominence="tertiary"
             />
@@ -234,6 +248,7 @@ interface SummaryLeftProps {
   rangeStart: number;
   rangeEnd: number;
   totalItems: number;
+  units?: string;
   isSmall: boolean;
 }
 
@@ -241,8 +256,10 @@ function SummaryLeft({
   rangeStart,
   rangeEnd,
   totalItems,
+  units,
   isSmall,
 }: SummaryLeftProps) {
+  const suffix = units ? ` ${units}` : "";
   return (
     <div className="flex flex-row gap-1 items-center w-fit h-fit px-1">
       {isSmall ? (
@@ -255,6 +272,7 @@ function SummaryLeft({
           <Text as="span" secondaryMono text03>
             {totalItems}
           </Text>
+          {suffix}
         </Text>
       ) : (
         <Text mainUiMuted text03>
@@ -266,6 +284,7 @@ function SummaryLeft({
           <Text as="span" mainUiMono text03>
             {totalItems}
           </Text>
+          {suffix}
         </Text>
       )}
     </div>

web/lib/opal/src/components/table/QualifierContainer.tsx

@@ -1,5 +1,5 @@
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 
 interface QualifierContainerProps {
   type: "head" | "cell";

web/lib/opal/src/components/table/README.md

@@ -0,0 +1,82 @@
+# Table
+
+Config-driven table component with sorting, pagination, column visibility,
+row selection, drag-and-drop reordering, and server-side mode.
+
+## Usage
+
+```tsx
+import { Table, createTableColumns } from "@opal/components";
+
+interface User {
+  id: string;
+  email: string;
+  name: string | null;
+  status: "active" | "invited";
+}
+
+const tc = createTableColumns<User>();
+
+const columns = [
+  tc.qualifier({ content: "avatar-user", getInitials: (r) => r.name?.[0] ?? "?" }),
+  tc.column("email", {
+    header: "Name",
+    weight: 22,
+    minWidth: 140,
+    cell: (email, row) => <span>{row.name ?? email}</span>,
+  }),
+  tc.column("status", {
+    header: "Status",
+    weight: 14,
+    cell: (status) => <span>{status}</span>,
+  }),
+  tc.actions(),
+];
+
+function UsersTable({ users }: { users: User[] }) {
+  return (
+    <Table
+      data={users}
+      columns={columns}
+      getRowId={(r) => r.id}
+      pageSize={10}
+      footer={{ mode: "summary" }}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `TData[]` | required | Row data array |
+| `columns` | `OnyxColumnDef<TData>[]` | required | Column definitions from `createTableColumns()` |
+| `getRowId` | `(row: TData) => string` | required | Unique row identifier |
+| `pageSize` | `number` | `10` | Rows per page (`Infinity` disables pagination) |
+| `size` | `"md" \| "lg"` | `"lg"` | Density variant |
+| `footer` | `DataTableFooterConfig` | — | Footer mode (`"selection"` or `"summary"`) |
+| `initialSorting` | `SortingState` | — | Initial sort state |
+| `initialColumnVisibility` | `VisibilityState` | — | Initial column visibility |
+| `draggable` | `DataTableDraggableConfig` | — | Enable drag-and-drop reordering |
+| `onSelectionChange` | `(ids: string[]) => void` | — | Selection callback |
+| `onRowClick` | `(row: TData) => void` | — | Row click handler |
+| `searchTerm` | `string` | — | Global text filter |
+| `height` | `number \| string` | — | Max scrollable height |
+| `headerBackground` | `string` | — | Sticky header background |
+| `serverSide` | `ServerSideConfig` | — | Server-side pagination/sorting/filtering |
+| `emptyState` | `ReactNode` | — | Empty state content |
+
+## Column Builder
+
+`createTableColumns<TData>()` returns a builder with:
+
+- `tc.qualifier(opts)` — leading avatar/icon/checkbox column
+- `tc.column(accessor, opts)` — data column with sorting/resizing
+- `tc.displayColumn(opts)` — non-accessor custom column
+- `tc.actions(opts)` — trailing actions column with visibility/sorting popovers
+
+## Footer Modes
+
+- **`"selection"`** — shows selection count, optional view/clear buttons, count pagination
+- **`"summary"`** — shows "Showing X~Y of Z", list pagination, optional extra element

web/lib/opal/src/components/table/Table.stories.tsx

@@ -0,0 +1,148 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Table, createTableColumns } from "@opal/components";
+
+// ---------------------------------------------------------------------------
+// Sample data
+// ---------------------------------------------------------------------------
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: "admin" | "user" | "viewer";
+  status: "active" | "invited" | "inactive";
+}
+
+const USERS: User[] = [
+  {
+    id: "1",
+    email: "alice@example.com",
+    name: "Alice Johnson",
+    role: "admin",
+    status: "active",
+  },
+  {
+    id: "2",
+    email: "bob@example.com",
+    name: "Bob Smith",
+    role: "user",
+    status: "active",
+  },
+  {
+    id: "3",
+    email: "carol@example.com",
+    name: "Carol White",
+    role: "viewer",
+    status: "invited",
+  },
+  {
+    id: "4",
+    email: "dave@example.com",
+    name: "Dave Brown",
+    role: "user",
+    status: "inactive",
+  },
+  {
+    id: "5",
+    email: "eve@example.com",
+    name: "Eve Davis",
+    role: "admin",
+    status: "active",
+  },
+  {
+    id: "6",
+    email: "frank@example.com",
+    name: "Frank Miller",
+    role: "viewer",
+    status: "active",
+  },
+  {
+    id: "7",
+    email: "grace@example.com",
+    name: "Grace Lee",
+    role: "user",
+    status: "invited",
+  },
+  {
+    id: "8",
+    email: "hank@example.com",
+    name: "Hank Wilson",
+    role: "user",
+    status: "active",
+  },
+  {
+    id: "9",
+    email: "iris@example.com",
+    name: "Iris Taylor",
+    role: "viewer",
+    status: "active",
+  },
+  {
+    id: "10",
+    email: "jack@example.com",
+    name: "Jack Moore",
+    role: "admin",
+    status: "active",
+  },
+  {
+    id: "11",
+    email: "kate@example.com",
+    name: "Kate Anderson",
+    role: "user",
+    status: "inactive",
+  },
+  {
+    id: "12",
+    email: "leo@example.com",
+    name: "Leo Thomas",
+    role: "viewer",
+    status: "active",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+const tc = createTableColumns<User>();
+
+const columns = [
+  tc.qualifier({
+    content: "avatar-user",
+    getInitials: (r) =>
+      r.name
+        .split(" ")
+        .map((n) => n[0])
+        .join(""),
+  }),
+  tc.column("name", { header: "Name", weight: 25, minWidth: 120 }),
+  tc.column("email", { header: "Email", weight: 30, minWidth: 160 }),
+  tc.column("role", { header: "Role", weight: 15, minWidth: 80 }),
+  tc.column("status", { header: "Status", weight: 15, minWidth: 80 }),
+  tc.actions(),
+];
+
+// ---------------------------------------------------------------------------
+// Story
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof Table> = {
+  title: "opal/components/Table",
+  component: Table,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Table>;
+
+export const Default: Story = {
+  render: () => (
+    <Table
+      data={USERS}
+      columns={columns}
+      getRowId={(r) => r.id}
+      pageSize={8}
+      footer={{ mode: "summary" }}
+    />
+  ),
+};

web/lib/opal/src/components/table/TableCell.tsx

@@ -1,6 +1,6 @@
-import { cn } from "@/lib/utils";
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { cn } from "@opal/utils";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import type { WithoutStyles } from "@/types";
 
 interface TableCellProps

web/lib/opal/src/components/table/TableElement.tsx

@@ -0,0 +1,71 @@
+import React from "react";
+import { cn } from "@opal/utils";
+import type { WithoutStyles } from "@/types";
+import type { ExtremaSizeVariants, SizeVariants } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type TableSize = Extract<SizeVariants, "md" | "lg">;
+type TableVariant = "rows" | "cards";
+type TableQualifier = "simple" | "avatar" | "icon";
+type SelectionBehavior = "no-select" | "single-select" | "multi-select";
+
+interface TableProps
+  extends WithoutStyles<React.TableHTMLAttributes<HTMLTableElement>> {
+  ref?: React.Ref<HTMLTableElement>;
+  /** Size preset for the table. @default "lg" */
+  size?: TableSize;
+  /** Visual row variant. @default "cards" */
+  variant?: TableVariant;
+  /** Row selection behavior. @default "no-select" */
+  selectionBehavior?: SelectionBehavior;
+  /** Leading qualifier column type. @default null */
+  qualifier?: TableQualifier;
+  /** Height behavior. `"fit"` = shrink to content, `"full"` = fill available space. */
+  heightVariant?: ExtremaSizeVariants;
+  /** Explicit pixel width for the table (e.g. from `table.getTotalSize()`).
+   *  When provided the table uses exactly this width instead of stretching
+   *  to fill its container, which prevents `table-layout: fixed` from
+   *  redistributing extra space across columns on resize. */
+  width?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+function Table({
+  ref,
+  size = "lg",
+  variant = "cards",
+  selectionBehavior = "no-select",
+  qualifier = "simple",
+  heightVariant,
+  width,
+  ...props
+}: TableProps) {
+  return (
+    <table
+      ref={ref}
+      className={cn("border-separate border-spacing-0", !width && "min-w-full")}
+      style={{ tableLayout: "fixed", width }}
+      data-size={size}
+      data-variant={variant}
+      data-selection={selectionBehavior}
+      data-qualifier={qualifier}
+      data-height={heightVariant}
+      {...props}
+    />
+  );
+}
+
+export default Table;
+export type {
+  TableProps,
+  TableSize,
+  TableVariant,
+  TableQualifier,
+  SelectionBehavior,
+};

web/lib/opal/src/components/table/TableHead.tsx

@@ -1,7 +1,7 @@
-import { cn } from "@/lib/utils";
+import { cn } from "@opal/utils";
 import Text from "@/refresh-components/texts/Text";
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import type { WithoutStyles } from "@/types";
 import { Button } from "@opal/components";
 import { SvgChevronDown, SvgChevronUp, SvgHandle, SvgSort } from "@opal/icons";
@@ -30,7 +30,7 @@ interface TableHeadCustomProps {
   icon?: (sorted: SortDirection) => IconFunctionComponent;
   /** Text alignment for the column. Defaults to `"left"`. */
   alignment?: "left" | "center" | "right";
-  /** Cell density. `"small"` uses tighter padding for denser layouts. */
+  /** Cell density. `"md"` uses tighter padding for denser layouts. */
   size?: TableSize;
   /** Column width in pixels. Applied as an inline style on the `<th>`. */
   width?: number;
@@ -88,7 +88,7 @@ export default function TableHead({
 }: TableHeadProps) {
   const contextSize = useTableSize();
   const resolvedSize = size ?? contextSize;
-  const isSmall = resolvedSize === "small";
+  const isSmall = resolvedSize === "md";
   return (
     <th
       {...thProps}

web/lib/opal/src/components/table/TableQualifier.tsx

@@ -1,12 +1,12 @@
 "use client";
 
 import React from "react";
-import { cn } from "@/lib/utils";
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { cn } from "@opal/utils";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import { SvgUser } from "@opal/icons";
 import type { IconFunctionComponent } from "@opal/types";
-import type { QualifierContentType } from "@/refresh-components/table/types";
+import type { QualifierContentType } from "@opal/components/table/types";
 import Checkbox from "@/refresh-components/inputs/Checkbox";
 import Text from "@/refresh-components/texts/Text";
 
@@ -35,8 +35,8 @@ interface TableQualifierProps {
 }
 
 const iconSizes = {
-  regular: 16,
-  small: 14,
+  lg: 16,
+  md: 14,
 } as const;
 
 function getQualifierStyles(selected: boolean, disabled: boolean) {
@@ -62,9 +62,9 @@ function getQualifierStyles(selected: boolean, disabled: boolean) {
     container: "bg-background-tint-01",
     icon: "stroke-text-03",
     overlay:
-      "flex opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 bg-background-tint-01",
+      "flex opacity-0 group-hover/row:opacity-100 group-focus-within/row:opacity-100 bg-background-tint-01",
     overlayImage:
-      "flex opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 bg-mask-01 group-hover:backdrop-blur-02 group-focus-within:backdrop-blur-02",
+      "flex opacity-0 group-hover/row:opacity-100 group-focus-within/row:opacity-100 bg-mask-01 group-hover/row:backdrop-blur-02 group-focus-within/row:backdrop-blur-02",
   };
 }
 
@@ -115,7 +115,7 @@ function TableQualifier({
           <div
             className={cn(
               "flex items-center justify-center rounded-full bg-background-neutral-inverted-00",
-              resolvedSize === "regular" ? "h-7 w-7" : "h-6 w-6"
+              resolvedSize === "lg" ? "h-7 w-7" : "h-6 w-6"
             )}
           >
             <Text
@@ -138,30 +138,36 @@ function TableQualifier({
     <div
       className={cn(
         "group relative inline-flex shrink-0 items-center justify-center",
-        resolvedSize === "regular" ? "h-9 w-9" : "h-7 w-7",
+        resolvedSize === "lg" ? "h-9 w-9" : "h-7 w-7",
         disabled ? "cursor-not-allowed" : "cursor-default",
         className
       )}
     >
-      {/* Inner qualifier container */}
-      <div
-        className={cn(
-          "flex items-center justify-center overflow-hidden transition-colors",
-          resolvedSize === "regular" ? "h-9 w-9" : "h-7 w-7",
-          isRound ? "rounded-full" : "rounded-08",
-          styles.container,
-          content === "image" && disabled && !selected && "opacity-50"
-        )}
-      >
-        {renderContent()}
-      </div>
+      {/* Inner qualifier container — no background for "simple" */}
+      {content !== "simple" && (
+        <div
+          className={cn(
+            "flex items-center justify-center overflow-hidden transition-colors",
+            resolvedSize === "lg" ? "h-9 w-9" : "h-7 w-7",
+            isRound ? "rounded-full" : "rounded-08",
+            styles.container,
+            content === "image" && disabled && !selected && "opacity-50"
+          )}
+        >
+          {renderContent()}
+        </div>
+      )}
 
       {/* Selection overlay */}
       {selectable && (
         <div
           className={cn(
             "absolute inset-0 items-center justify-center",
-            isRound ? "rounded-full" : "rounded-08",
+            content === "simple"
+              ? "flex"
+              : isRound
+                ? "rounded-full"
+                : "rounded-08",
             content === "simple"
               ? "flex"
               : content === "image"

web/lib/opal/src/components/table/TableRow.tsx

@@ -1,8 +1,8 @@
 "use client";
 
-import { cn } from "@/lib/utils";
-import { useTableSize } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { cn } from "@opal/utils";
+import { useTableSize } from "@opal/components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import type { WithoutStyles } from "@/types";
 import { useSortable } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
@@ -18,8 +18,6 @@ interface TableRowProps
   selected?: boolean;
   /** Disables interaction and applies disabled styling */
   disabled?: boolean;
-  /** Visual variant: "table" adds a bottom border, "list" adds rounded corners. Defaults to "list". */
-  variant?: "table" | "list";
   /** When provided, makes this row sortable via @dnd-kit */
   sortableId?: string;
   /** Show drag handle overlay. Defaults to true when sortableId is set. */
@@ -36,7 +34,6 @@ function SortableTableRow({
   sortableId,
   showDragHandle = true,
   size,
-  variant = "list",
   selected,
   disabled,
   ref: _externalRef,
@@ -66,7 +63,6 @@ function SortableTableRow({
       ref={setNodeRef}
       style={style}
       className="tbl-row group/row"
-      data-variant={variant}
       data-drag-handle={showDragHandle || undefined}
       data-selected={selected || undefined}
       data-disabled={disabled || undefined}
@@ -95,7 +91,7 @@ function SortableTableRow({
             {...listeners}
           >
             <SvgHandle
-              size={resolvedSize === "small" ? 12 : 16}
+              size={resolvedSize === "md" ? 12 : 16}
               className="text-border-02"
             />
           </button>
@@ -113,7 +109,6 @@ function TableRow({
   sortableId,
   showDragHandle,
   size,
-  variant = "list",
   selected,
   disabled,
   ref,
@@ -125,7 +120,6 @@ function TableRow({
         sortableId={sortableId}
         showDragHandle={showDragHandle}
         size={size}
-        variant={variant}
         selected={selected}
         disabled={disabled}
         ref={ref}
@@ -138,7 +132,6 @@ function TableRow({
     <tr
       ref={ref}
       className="tbl-row group/row"
-      data-variant={variant}
       data-selected={selected || undefined}
       data-disabled={disabled || undefined}
       {...props}

web/lib/opal/src/components/table/TableSizeContext.tsx

@@ -1,10 +1,11 @@
 "use client";
 
 import { createContext, useContext } from "react";
+import type { SizeVariants } from "@opal/types";
 
-type TableSize = "regular" | "small";
+type TableSize = Extract<SizeVariants, "md" | "lg">;
 
-const TableSizeContext = createContext<TableSize>("regular");
+const TableSizeContext = createContext<TableSize>("lg");
 
 interface TableSizeProviderProps {
   size: TableSize;

web/lib/opal/src/components/table/columns.ts

@@ -13,10 +13,10 @@ import type {
   OnyxDataColumn,
   OnyxDisplayColumn,
   OnyxActionsColumn,
-} from "@/refresh-components/table/types";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+} from "@opal/components/table/types";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
 import type { IconFunctionComponent } from "@opal/types";
-import type { SortDirection } from "@/refresh-components/table/TableHead";
+import type { SortDirection } from "@opal/components/table/TableHead";
 
 // ---------------------------------------------------------------------------
 // Qualifier column config
@@ -160,7 +160,7 @@ export function createTableColumns<TData>(): TableColumnsBuilder<TData> {
         id: "qualifier",
         def,
         width: (size: TableSize) =>
-          size === "small" ? { fixed: 40 } : { fixed: 56 },
+          size === "md" ? { fixed: 36 } : { fixed: 44 },
         content,
         headerContentType: config?.headerContentType,
         getInitials: config?.getInitials,
@@ -241,14 +241,29 @@ export function createTableColumns<TData>(): TableColumnsBuilder<TData> {
           : () => null,
       };
 
+      const showVisibility = config?.showColumnVisibility ?? true;
+      const showSorting = config?.showSorting ?? true;
+      const buttonCount = (showVisibility ? 1 : 0) + (showSorting ? 1 : 0);
+
+      // Icon button sizes: "md" button = 28px, "sm" button = 24px
+      // px-1 on .tbl-actions = 4px each side = 8px total
+      const BUTTON_MD = 28;
+      const BUTTON_SM = 24;
+      const PADDING = 8;
+
       return {
         kind: "actions",
         id: "__actions",
         def,
-        width: (size: TableSize) =>
-          size === "small" ? { fixed: 20 } : { fixed: 88 },
-        showColumnVisibility: config?.showColumnVisibility ?? true,
-        showSorting: config?.showSorting ?? true,
+        width: (size: TableSize) => ({
+          fixed:
+            Math.max(
+              buttonCount * (size === "md" ? BUTTON_SM : BUTTON_MD),
+              size === "md" ? BUTTON_SM : BUTTON_MD
+            ) + PADDING,
+        }),
+        showColumnVisibility: showVisibility,
+        showSorting: showSorting,
         sortingFooterText: config?.sortingFooterText,
       };
     },

web/lib/opal/src/components/table/components.tsx

@@ -1,39 +1,56 @@
 "use client";
 "use no memo";
 
+import "@opal/components/table/styles.css";
+
 import { useEffect, useMemo } from "react";
 import { flexRender } from "@tanstack/react-table";
 import useDataTable, {
   toOnyxSortDirection,
-} from "@/refresh-components/table/hooks/useDataTable";
-import useColumnWidths from "@/refresh-components/table/hooks/useColumnWidths";
-import useDraggableRows from "@/refresh-components/table/hooks/useDraggableRows";
-import Table from "@/refresh-components/table/Table";
-import TableHeader from "@/refresh-components/table/TableHeader";
-import TableBody from "@/refresh-components/table/TableBody";
-import TableRow from "@/refresh-components/table/TableRow";
-import TableHead from "@/refresh-components/table/TableHead";
-import TableCell from "@/refresh-components/table/TableCell";
-import TableQualifier from "@/refresh-components/table/TableQualifier";
-import QualifierContainer from "@/refresh-components/table/QualifierContainer";
-import ActionsContainer from "@/refresh-components/table/ActionsContainer";
-import DragOverlayRow from "@/refresh-components/table/DragOverlayRow";
-import Footer from "@/refresh-components/table/Footer";
-import { TableSizeProvider } from "@/refresh-components/table/TableSizeContext";
-import { ColumnVisibilityPopover } from "@/refresh-components/table/ColumnVisibilityPopover";
-import { SortingPopover } from "@/refresh-components/table/SortingPopover";
-import type { WidthConfig } from "@/refresh-components/table/hooks/useColumnWidths";
+} from "@opal/components/table/hooks/useDataTable";
+import useColumnWidths from "@opal/components/table/hooks/useColumnWidths";
+import useDraggableRows from "@opal/components/table/hooks/useDraggableRows";
+import TableElement from "@opal/components/table/TableElement";
+import TableHeader from "@opal/components/table/TableHeader";
+import TableBody from "@opal/components/table/TableBody";
+import TableRow from "@opal/components/table/TableRow";
+import TableHead from "@opal/components/table/TableHead";
+import TableCell from "@opal/components/table/TableCell";
+import TableQualifier from "@opal/components/table/TableQualifier";
+import QualifierContainer from "@opal/components/table/QualifierContainer";
+import ActionsContainer from "@opal/components/table/ActionsContainer";
+import DragOverlayRow from "@opal/components/table/DragOverlayRow";
+import Footer from "@opal/components/table/Footer";
+import Checkbox from "@/refresh-components/inputs/Checkbox";
+import { TableSizeProvider } from "@opal/components/table/TableSizeContext";
+import { ColumnVisibilityPopover } from "@opal/components/table/ColumnVisibilityPopover";
+import { SortingPopover } from "@opal/components/table/ColumnSortabilityPopover";
+import type { WidthConfig } from "@opal/components/table/hooks/useColumnWidths";
 import type { ColumnDef } from "@tanstack/react-table";
-import { cn } from "@/lib/utils";
+import { cn } from "@opal/utils";
 import type {
-  DataTableProps,
+  DataTableProps as BaseDataTableProps,
   DataTableFooterConfig,
   OnyxColumnDef,
   OnyxDataColumn,
   OnyxQualifierColumn,
   OnyxActionsColumn,
-} from "@/refresh-components/table/types";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+} from "@opal/components/table/types";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
+
+// ---------------------------------------------------------------------------
+// Qualifier × SelectionBehavior
+// ---------------------------------------------------------------------------
+
+type Qualifier = "simple" | "avatar" | "icon";
+type SelectionBehavior = "no-select" | "single-select" | "multi-select";
+
+export type DataTableProps<TData> = BaseDataTableProps<TData> & {
+  /** Leading qualifier column type. @default "simple" */
+  qualifier?: Qualifier;
+  /** Row selection behavior. @default "no-select" */
+  selectionBehavior?: SelectionBehavior;
+};
 
 // ---------------------------------------------------------------------------
 // Internal: resolve size-dependent widths and build TanStack columns
@@ -57,6 +74,7 @@ function processColumns<TData>(
   const columnMinWidths: Record<string, number> = {};
   const columnKindMap = new Map<string, OnyxColumnDef<TData>>();
   let qualifierColumn: OnyxQualifierColumn<TData> | null = null;
+  let firstDataColumnSeen = false;
 
   for (const col of columns) {
     const resolvedWidth =
@@ -70,6 +88,12 @@ function processColumns<TData>(
         "fixed" in resolvedWidth ? resolvedWidth.fixed : resolvedWidth.weight,
     };
 
+    // First data column is never hideable
+    if (col.kind === "data" && !firstDataColumnSeen) {
+      firstDataColumnSeen = true;
+      clonedDef.enableHiding = false;
+    }
+
     tanstackColumns.push(clonedDef);
 
     const id = col.id;
@@ -113,10 +137,10 @@ function processColumns<TData>(
  *   tc.actions(),
  * ];
  *
- * <DataTable data={items} columns={columns} footer={{ mode: "selection" }} />
+ * <Table data={items} columns={columns} footer={{}} />
  * ```
  */
-export default function DataTable<TData>(props: DataTableProps<TData>) {
+export function Table<TData>(props: DataTableProps<TData>) {
   const {
     data,
     columns,
@@ -126,7 +150,10 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
     initialColumnVisibility,
     draggable,
     footer,
-    size = "regular",
+    size = "lg",
+    variant = "cards",
+    qualifier = "simple",
+    selectionBehavior = "no-select",
     onSelectionChange,
     onRowClick,
     searchTerm,
@@ -138,9 +165,37 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
 
   const effectivePageSize = pageSize ?? (footer ? 10 : data.length);
 
+  // Whether the qualifier column should exist in the DOM.
+  // "simple" only gets a qualifier column for multi-select (checkboxes).
+  // "simple" + no-select/single-select = no qualifier column — single-select
+  // uses row-level background coloring instead.
+  const hasQualifierColumn =
+    qualifier !== "simple" || selectionBehavior === "multi-select";
+
   // 1. Process columns (memoized on columns + size)
   const { tanstackColumns, widthConfig, qualifierColumn, columnKindMap } =
-    useMemo(() => processColumns(columns, size), [columns, size]);
+    useMemo(() => {
+      const processed = processColumns(columns, size);
+      if (!hasQualifierColumn) {
+        // Remove qualifier from TanStack columns and width config entirely
+        return {
+          ...processed,
+          tanstackColumns: processed.tanstackColumns.filter(
+            (c) => c.id !== "qualifier"
+          ),
+          widthConfig: {
+            ...processed.widthConfig,
+            fixedColumnIds: new Set(
+              Array.from(processed.widthConfig.fixedColumnIds).filter(
+                (id) => id !== "qualifier"
+              )
+            ),
+          },
+          qualifierColumn: null,
+        };
+      }
+      return processed;
+    }, [columns, size, hasQualifierColumn]);
 
   // 2. Call useDataTable
   const {
@@ -155,7 +210,9 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
     selectedRowIds,
     clearSelection,
     toggleAllPageRowsSelected,
+    toggleAllRowsSelected,
     isAllPageRowsSelected,
+    isAllRowsSelected,
     isViewingSelected,
     enterViewMode,
     exitViewMode,
@@ -193,16 +250,6 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
       );
     }
   }, [!!serverSide, !!draggable]); // eslint-disable-line react-hooks/exhaustive-deps
-  const footerShowView =
-    footer?.mode === "selection" ? footer.showView : undefined;
-  useEffect(() => {
-    if (process.env.NODE_ENV !== "production" && serverSide && footerShowView) {
-      console.warn(
-        "DataTable: `showView` is ignored when `serverSide` is enabled. " +
-          "View mode requires client-side filtering."
-      );
-    }
-  }, [!!serverSide, !!footerShowView]); // eslint-disable-line react-hooks/exhaustive-deps
   const effectiveDraggable = serverSide ? undefined : draggable;
   const draggableReturn = useDraggableRows({
     data,
@@ -212,10 +259,11 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
   });
 
   const hasDraggable = !!effectiveDraggable;
-  const rowVariant = hasDraggable ? "table" : "list";
 
-  const isSelectable =
-    qualifierColumn != null && qualifierColumn.selectable !== false;
+  const isSelectable = selectionBehavior !== "no-select";
+  const isMultiSelect = selectionBehavior === "multi-select";
+  // Checkboxes appear for any selectable table
+  const showQualifierCheckbox = isSelectable;
 
   // ---------------------------------------------------------------------------
   // Render
@@ -224,11 +272,13 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
   const isServerLoading = !!serverSide?.isLoading;
 
   function renderFooter(footerConfig: DataTableFooterConfig) {
-    if (footerConfig.mode === "selection") {
+    // Mode derived from selectionBehavior — single/multi-select use selection
+    // footer, no-select uses summary footer.
+    if (isSelectable) {
       return (
         <Footer
           mode="selection"
-          multiSelect={footerConfig.multiSelect !== false}
+          multiSelect={isMultiSelect}
           selectionState={selectionState}
           selectedCount={selectedCount}
           onClear={
@@ -239,22 +289,24 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
             })
           }
           onView={
-            footerConfig.showView
+            !serverSide
               ? isViewingSelected
                 ? exitViewMode
                 : enterViewMode
               : undefined
           }
+          isViewingSelected={isViewingSelected}
           pageSize={resolvedPageSize}
           totalItems={totalItems}
           currentPage={currentPage}
           totalPages={totalPages}
           onPageChange={setPage}
+          units={footerConfig.units}
         />
       );
     }
 
-    // Summary mode
+    // Summary mode (no-select only)
     const rangeStart =
       totalItems === 0
         ? 0
@@ -275,6 +327,7 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
         totalPages={totalPages}
         onPageChange={setPage}
         leftExtra={footerConfig.leftExtra}
+        units={footerConfig.units}
       />
     );
   }
@@ -303,7 +356,10 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
               : undefined),
           }}
         >
-          <Table
+          <TableElement
+            size={size}
+            variant={variant}
+            selectionBehavior={selectionBehavior}
             width={
               Object.keys(columnWidths).length > 0
                 ? Object.values(columnWidths).reduce((sum, w) => sum + w, 0)
@@ -311,7 +367,7 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
             }
           >
             <colgroup>
-              {table.getAllLeafColumns().map((col) => (
+              {table.getVisibleLeafColumns().map((col) => (
                 <col
                   key={col.id}
                   style={
@@ -328,28 +384,26 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                   {headerGroup.headers.map((header, headerIndex) => {
                     const colDef = columnKindMap.get(header.id);
 
-                    // Qualifier header
+                    // Qualifier header — select-all checkbox only for multi-select
                     if (colDef?.kind === "qualifier") {
-                      if (qualifierColumn?.header === false) {
-                        return (
-                          <QualifierContainer key={header.id} type="head" />
-                        );
-                      }
                       return (
                         <QualifierContainer key={header.id} type="head">
-                          <TableQualifier
-                            content={
-                              qualifierColumn?.headerContentType ?? "simple"
-                            }
-                            selectable={isSelectable}
-                            selected={isSelectable && isAllPageRowsSelected}
-                            onSelectChange={
-                              isSelectable
-                                ? (checked) =>
-                                    toggleAllPageRowsSelected(checked)
-                                : undefined
-                            }
-                          />
+                          {isMultiSelect && (
+                            <Checkbox
+                              checked={isAllRowsSelected}
+                              indeterminate={
+                                !isAllRowsSelected && selectedCount > 0
+                              }
+                              onCheckedChange={(checked) => {
+                                // Indeterminate → clear all; otherwise toggle normally
+                                if (!isAllRowsSelected && selectedCount > 0) {
+                                  toggleAllRowsSelected(false);
+                                } else {
+                                  toggleAllRowsSelected(checked);
+                                }
+                              }}
+                            />
+                          )}
                         </QualifierContainer>
                       );
                     }
@@ -437,7 +491,6 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                       return (
                         <DragOverlayRow
                           row={row}
-                          variant={rowVariant}
                           columnWidths={columnWidths}
                           columnKindMap={columnKindMap}
                           qualifierColumn={qualifierColumn}
@@ -461,7 +514,6 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                 return (
                   <TableRow
                     key={row.id}
-                    variant={rowVariant}
                     sortableId={rowId}
                     selected={row.getIsSelected()}
                     onClick={() => {
@@ -474,6 +526,10 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                       if (onRowClick) {
                         onRowClick(row.original);
                       } else if (isSelectable) {
+                        if (!isMultiSelect) {
+                          // single-select: clear all, then select this row
+                          table.toggleAllRowsSelected(false);
+                        }
                         row.toggleSelected();
                       }
                     }}
@@ -484,6 +540,13 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                       // Qualifier cell
                       if (cellColDef?.kind === "qualifier") {
                         const qDef = cellColDef as OnyxQualifierColumn<TData>;
+
+                        // Resolve content based on the qualifier prop:
+                        // - "simple" renders nothing (checkbox only when selectable)
+                        // - "avatar"/"icon" render from column config
+                        const qualifierContent =
+                          qualifier === "simple" ? "simple" : qDef.content;
+
                         return (
                           <QualifierContainer
                             key={cell.id}
@@ -491,15 +554,20 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                             onClick={(e) => e.stopPropagation()}
                           >
                             <TableQualifier
-                              content={qDef.content}
+                              content={qualifierContent}
                               initials={qDef.getInitials?.(row.original)}
                               icon={qDef.getIcon?.(row.original)}
                               imageSrc={qDef.getImageSrc?.(row.original)}
-                              selectable={isSelectable}
-                              selected={isSelectable && row.getIsSelected()}
+                              selectable={showQualifierCheckbox}
+                              selected={
+                                showQualifierCheckbox && row.getIsSelected()
+                              }
                               onSelectChange={
-                                isSelectable
+                                showQualifierCheckbox
                                   ? (checked) => {
+                                      if (!isMultiSelect) {
+                                        table.toggleAllRowsSelected(false);
+                                      }
                                       row.toggleSelected(checked);
                                     }
                                   : undefined
@@ -539,7 +607,7 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                 );
               })}
             </TableBody>
-          </Table>
+          </TableElement>
         </div>
 
         {footer && renderFooter(footer)}

web/lib/opal/src/components/table/hooks/useDataTable.ts

@@ -153,6 +153,10 @@ interface UseDataTableReturn<TData extends RowData> {
   clearSelection: () => void;
   /** Select or deselect all rows on the current page. */
   toggleAllPageRowsSelected: (selected: boolean) => void;
+  /** Select or deselect all rows across all pages. */
+  toggleAllRowsSelected: (selected: boolean) => void;
+  /** Whether every row across all pages is selected. */
+  isAllRowsSelected: boolean;
 
   // View-mode (filter to selected rows)
   /** Whether the table is currently filtered to show only selected rows. */
@@ -407,6 +411,16 @@ export default function useDataTable<TData extends RowData>(
     table.toggleAllPageRowsSelected(selected);
   };
 
+  // TODO (@raunakab): In server-side mode, these only operate on the loaded
+  // page data, not all rows across all pages. TanStack can't select rows it
+  // doesn't have. Fixing this requires a server-side callback (e.g.
+  // `onSelectAll`) and a `totalItems`-aware selection model.
+  const toggleAllRowsSelected = (selected: boolean) => {
+    table.toggleAllRowsSelected(selected);
+  };
+
+  const isAllRowsSelected = table.getIsAllRowsSelected();
+
   // ---- view mode (filter to selected rows) --------------------------------
   const isViewingSelected = globalFilter.selectedIds != null;
 
@@ -439,8 +453,10 @@ export default function useDataTable<TData extends RowData>(
     selectedCount,
     selectedRowIds,
     isAllPageRowsSelected,
+    isAllRowsSelected,
     clearSelection,
     toggleAllPageRowsSelected,
+    toggleAllRowsSelected,
     isViewingSelected,
     enterViewMode,
     exitViewMode,

web/lib/opal/src/components/table/styles.css

@@ -0,0 +1,164 @@
+/* Imports shared timing tokens (--interactive-duration, --interactive-easing) */
+@import "@opal/core/interactive/shared.css";
+
+/* ---------------------------------------------------------------------------
+ * Table primitives — data-attribute driven styling
+ * Follows the same pattern as card.css / line-item.css.
+ * ------------------------------------------------------------------------- */
+
+/* ---- TableCell ---- */
+
+.tbl-cell[data-size="lg"] {
+  @apply px-1 py-0.5;
+}
+.tbl-cell[data-size="md"] {
+  @apply pl-0.5 pr-1.5 py-1.5;
+}
+
+.tbl-cell-inner[data-size="lg"] {
+  @apply h-10 px-1;
+}
+.tbl-cell-inner[data-size="md"] {
+  @apply h-6 px-0.5;
+}
+
+/* ---- TableHead ---- */
+
+.table-head {
+  @apply relative sticky top-0 z-20;
+  background: var(--table-header-bg, transparent);
+}
+.table-head[data-size="lg"] {
+  @apply px-2 py-1;
+}
+.table-head[data-size="md"] {
+  @apply px-2 py-1;
+}
+.table-head[data-bottom-border] {
+  @apply border-b border-transparent hover:border-border-03;
+}
+
+/* Inner text wrapper */
+.table-head[data-size="lg"] .table-head-label {
+  @apply py-2 px-0.5;
+}
+.table-head[data-size="md"] .table-head-label {
+  @apply py-1;
+}
+
+/* Sort button wrapper */
+.table-head[data-size="lg"] .table-head-sort {
+  @apply py-1.5;
+}
+
+/* ---- TableRow (base) ---- */
+
+.tbl-row > td {
+  @apply bg-background-tint-00;
+  transition: background-color var(--interactive-duration)
+    var(--interactive-easing);
+}
+
+.tbl-row[data-selected] > td {
+  @apply bg-[var(--action-link-01)];
+}
+
+.tbl-row[data-disabled] {
+  @apply pointer-events-none;
+}
+
+/* Suppress default focus ring on rows — the row bg is the indicator */
+.tbl-row:focus,
+.tbl-row:focus-visible {
+  outline: none;
+}
+
+/* ---- variant="rows" — traditional borders, no gaps ---- */
+
+table[data-variant="rows"] .tbl-row > td {
+  @apply border-b border-border-01;
+}
+
+/* Hover/focus only for selectable tables */
+table[data-variant="rows"][data-selection="single-select"] .tbl-row,
+table[data-variant="rows"][data-selection="multi-select"] .tbl-row {
+  @apply cursor-pointer;
+}
+table[data-variant="rows"][data-selection="single-select"] .tbl-row:hover > td,
+table[data-variant="rows"][data-selection="multi-select"] .tbl-row:hover > td {
+  @apply bg-background-tint-02;
+}
+table[data-variant="rows"] .tbl-row:focus-visible > td,
+table[data-variant="rows"] .tbl-row:has(:focus-visible) > td {
+  @apply bg-action-link-01;
+}
+
+/* ---- variant="cards" — rounded cards with gap ---- */
+
+table[data-variant="cards"] .tbl-row > td {
+  @apply bg-clip-padding border-y-[2px] border-x-0 border-transparent;
+}
+table[data-variant="cards"] .tbl-row > td:first-child {
+  @apply rounded-l-12;
+}
+table[data-variant="cards"] .tbl-row > td:last-child {
+  @apply rounded-r-12;
+}
+
+/* When a drag handle is present the second-to-last td gets the rounding */
+table[data-variant="cards"] .tbl-row[data-drag-handle] > td:nth-last-child(2) {
+  @apply rounded-r-12;
+}
+table[data-variant="cards"] .tbl-row[data-drag-handle] > td:last-child {
+  border-radius: 0;
+}
+
+/* Hover/focus only for selectable tables */
+table[data-variant="cards"][data-selection="single-select"] .tbl-row,
+table[data-variant="cards"][data-selection="multi-select"] .tbl-row {
+  @apply cursor-pointer;
+}
+table[data-variant="cards"][data-selection="single-select"] .tbl-row:hover > td,
+table[data-variant="cards"][data-selection="multi-select"] .tbl-row:hover > td {
+  @apply bg-background-tint-02;
+}
+table[data-variant="cards"] .tbl-row:focus-visible > td,
+table[data-variant="cards"] .tbl-row:has(:focus-visible) > td {
+  @apply bg-action-link-01;
+}
+
+/* ---- QualifierContainer ---- */
+
+.tbl-qualifier[data-type="head"] {
+  @apply w-px whitespace-nowrap py-1 sticky top-0 z-20;
+  background: var(--table-header-bg, transparent);
+}
+.tbl-qualifier[data-type="head"][data-size="md"] {
+  @apply py-0.5;
+}
+
+.tbl-qualifier[data-type="cell"] {
+  @apply w-px whitespace-nowrap py-1;
+}
+.tbl-qualifier[data-type="cell"][data-size="md"] {
+  @apply py-0.5;
+}
+
+/* ---- ActionsContainer ---- */
+
+.tbl-actions {
+  @apply sticky right-0 w-px whitespace-nowrap px-1;
+}
+.tbl-actions[data-type="head"] {
+  @apply z-30 sticky top-0 px-2 py-1;
+  background: var(--table-header-bg, transparent);
+}
+
+/* ---- Footer ---- */
+
+.table-footer[data-size="lg"] {
+  @apply min-h-[2.75rem];
+}
+.table-footer[data-size="md"] {
+  @apply min-h-[2.25rem];
+}

web/lib/opal/src/components/table/types.ts

@@ -4,9 +4,10 @@ import type {
   SortingState,
   VisibilityState,
 } from "@tanstack/react-table";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@opal/components/table/TableSizeContext";
+import type { TableVariant } from "@opal/components/table/TableElement";
 import type { IconFunctionComponent } from "@opal/types";
-import type { SortDirection } from "@/refresh-components/table/TableHead";
+import type { SortDirection } from "@opal/components/table/TableHead";
 
 // ---------------------------------------------------------------------------
 // Column width (mirrors useColumnWidths types)
@@ -129,26 +130,16 @@ export interface DataTableDraggableConfig {
   ) => void | Promise<void>;
 }
 
-export interface DataTableFooterSelection {
-  mode: "selection";
-  /** Whether the table supports selecting multiple rows. @default true */
-  multiSelect?: boolean;
-  /** When true, shows a "View" button that filters the table to only selected rows. @default false */
-  showView?: boolean;
-  /** Handler for the "Clear" button. When omitted, the default clearSelection is used. */
+/** Footer configuration. Mode is derived from `selectionBehavior` automatically. */
+export interface DataTableFooterConfig {
+  /** Handler for the "Clear" button (multi-select only). When omitted, the default clearSelection is used. */
   onClear?: () => void;
-}
-
-export interface DataTableFooterSummary {
-  mode: "summary";
-  /** Optional extra element rendered after the summary text (e.g. a download icon). */
+  /** Unit label for count pagination, e.g. "users", "documents" (multi-select only). */
+  units?: string;
+  /** Optional extra element rendered after the summary text, e.g. a download icon (summary mode only). */
   leftExtra?: ReactNode;
 }
 
-export type DataTableFooterConfig =
-  | DataTableFooterSelection
-  | DataTableFooterSummary;
-
 export interface DataTableProps<TData> {
   /** Row data array. */
   data: TData[];
@@ -166,8 +157,10 @@ export interface DataTableProps<TData> {
   draggable?: DataTableDraggableConfig;
   /** Footer configuration. */
   footer?: DataTableFooterConfig;
-  /** Table size variant. @default "regular" */
+  /** Table size variant. @default "lg" */
   size?: TableSize;
+  /** Visual row variant. @default "cards" */
+  variant?: TableVariant;
   /** Called whenever the set of selected row IDs changes. Receives IDs produced by `getRowId`. */
   onSelectionChange?: (selectedIds: string[]) => void;
   /** Called when a row is clicked (replaces the default selection toggle). */

web/lib/opal/src/core/animations/Hoverable.stories.tsx

@@ -0,0 +1,162 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Hoverable } from "@opal/core";
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: "Core/Hoverable",
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Group mode — hovering the root reveals hidden items. */
+export const GroupMode: StoryObj = {
+  render: () => (
+    <Hoverable.Root group="demo">
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "0.75rem",
+          padding: "1rem",
+          border: "1px solid var(--border-02)",
+          borderRadius: "0.5rem",
+          minWidth: 260,
+        }}
+      >
+        <span style={{ color: "var(--text-01)" }}>Hover this card</span>
+        <Hoverable.Item group="demo" variant="opacity-on-hover">
+          <span style={{ color: "var(--text-03)" }}>✓ Revealed</span>
+        </Hoverable.Item>
+      </div>
+    </Hoverable.Root>
+  ),
+};
+
+/** Local mode — hovering the item itself reveals it (no Root needed). */
+export const LocalMode: StoryObj = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: "0.75rem",
+        padding: "1rem",
+      }}
+    >
+      <span style={{ color: "var(--text-01)" }}>Hover the icon →</span>
+      <Hoverable.Item variant="opacity-on-hover">
+        <span style={{ fontSize: "1.25rem" }}>🗑</span>
+      </Hoverable.Item>
+    </div>
+  ),
+};
+
+/** Multiple independent groups on the same page. */
+export const MultipleGroups: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "0.75rem" }}>
+      {(["alpha", "beta"] as const).map((group) => (
+        <Hoverable.Root key={group} group={group}>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "0.75rem",
+              padding: "1rem",
+              border: "1px solid var(--border-02)",
+              borderRadius: "0.5rem",
+            }}
+          >
+            <span style={{ color: "var(--text-01)" }}>Group: {group}</span>
+            <Hoverable.Item group={group} variant="opacity-on-hover">
+              <span style={{ color: "var(--text-03)" }}>✓ Revealed</span>
+            </Hoverable.Item>
+          </div>
+        </Hoverable.Root>
+      ))}
+    </div>
+  ),
+};
+
+/** Multiple items revealed by a single root. */
+export const MultipleItems: StoryObj = {
+  render: () => (
+    <Hoverable.Root group="multi">
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "0.75rem",
+          padding: "1rem",
+          border: "1px solid var(--border-02)",
+          borderRadius: "0.5rem",
+        }}
+      >
+        <span style={{ color: "var(--text-01)" }}>Hover to reveal all</span>
+        <Hoverable.Item group="multi" variant="opacity-on-hover">
+          <span>Edit</span>
+        </Hoverable.Item>
+        <Hoverable.Item group="multi" variant="opacity-on-hover">
+          <span>Delete</span>
+        </Hoverable.Item>
+        <Hoverable.Item group="multi" variant="opacity-on-hover">
+          <span>Share</span>
+        </Hoverable.Item>
+      </div>
+    </Hoverable.Root>
+  ),
+};
+
+/** Nested groups — inner and outer hover independently. */
+export const NestedGroups: StoryObj = {
+  render: () => (
+    <Hoverable.Root group="outer">
+      <div
+        style={{
+          padding: "1rem",
+          border: "1px solid var(--border-02)",
+          borderRadius: "0.5rem",
+          display: "flex",
+          flexDirection: "column",
+          gap: "0.75rem",
+        }}
+      >
+        <div style={{ display: "flex", alignItems: "center", gap: "0.75rem" }}>
+          <span style={{ color: "var(--text-01)" }}>Outer card</span>
+          <Hoverable.Item group="outer" variant="opacity-on-hover">
+            <span style={{ color: "var(--text-03)" }}>Outer action</span>
+          </Hoverable.Item>
+        </div>
+
+        <Hoverable.Root group="inner">
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "0.75rem",
+              padding: "0.75rem",
+              border: "1px solid var(--border-03)",
+              borderRadius: "0.375rem",
+            }}
+          >
+            <span style={{ color: "var(--text-02)" }}>Inner card</span>
+            <Hoverable.Item group="inner" variant="opacity-on-hover">
+              <span style={{ color: "var(--text-03)" }}>Inner action</span>
+            </Hoverable.Item>
+          </div>
+        </Hoverable.Root>
+      </div>
+    </Hoverable.Root>
+  ),
+};

web/lib/opal/src/core/hoverable/Hoverable.stories.tsx

@@ -1,127 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { Hoverable } from "@opal/core";
-import SvgX from "@opal/icons/x";
-
-// ---------------------------------------------------------------------------
-// Shared styles
-// ---------------------------------------------------------------------------
-
-const cardStyle: React.CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  gap: "1rem",
-  padding: "0.75rem 1rem",
-  borderRadius: "0.5rem",
-  border: "1px solid var(--border-02)",
-  background: "var(--background-neutral-01)",
-  minWidth: 220,
-};
-
-const labelStyle: React.CSSProperties = {
-  fontSize: "0.875rem",
-  fontWeight: 500,
-};
-
-// ---------------------------------------------------------------------------
-// Meta
-// ---------------------------------------------------------------------------
-
-const meta: Meta = {
-  title: "Core/Hoverable",
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-  },
-};
-
-export default meta;
-
-// ---------------------------------------------------------------------------
-// Stories
-// ---------------------------------------------------------------------------
-
-/**
- * Local hover mode -- no `group` prop on the Item.
- * The icon only appears when you hover directly over the Item element itself.
- */
-export const LocalHover: StoryObj = {
-  render: () => (
-    <div style={cardStyle}>
-      <span style={labelStyle}>Hover this card area</span>
-
-      <Hoverable.Item variant="opacity-on-hover">
-        <SvgX width={16} height={16} />
-      </Hoverable.Item>
-    </div>
-  ),
-};
-
-/**
- * Group hover mode -- hovering anywhere inside the Root reveals the Item.
- */
-export const GroupHover: StoryObj = {
-  render: () => (
-    <Hoverable.Root group="card">
-      <div style={cardStyle}>
-        <span style={labelStyle}>Hover anywhere on this card</span>
-
-        <Hoverable.Item group="card" variant="opacity-on-hover">
-          <SvgX width={16} height={16} />
-        </Hoverable.Item>
-      </div>
-    </Hoverable.Root>
-  ),
-};
-
-/**
- * Nested groups demonstrating isolation.
- *
- * - Hovering the outer card reveals only the outer icon.
- * - Hovering the inner card reveals only the inner icon.
- */
-export const NestedGroups: StoryObj = {
-  render: () => (
-    <Hoverable.Root group="outer">
-      <div
-        style={{
-          ...cardStyle,
-          flexDirection: "column",
-          alignItems: "stretch",
-          gap: "0.75rem",
-          padding: "1rem",
-          minWidth: 300,
-        }}
-      >
-        <div
-          style={{
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "space-between",
-          }}
-        >
-          <span style={labelStyle}>Outer card</span>
-
-          <Hoverable.Item group="outer" variant="opacity-on-hover">
-            <SvgX width={16} height={16} />
-          </Hoverable.Item>
-        </div>
-
-        <Hoverable.Root group="inner">
-          <div
-            style={{
-              ...cardStyle,
-              background: "var(--background-neutral-02)",
-            }}
-          >
-            <span style={labelStyle}>Inner card</span>
-
-            <Hoverable.Item group="inner" variant="opacity-on-hover">
-              <SvgX width={16} height={16} />
-            </Hoverable.Item>
-          </div>
-        </Hoverable.Root>
-      </div>
-    </Hoverable.Root>
-  ),
-};

web/lib/opal/src/core/interactive/shared.css

@@ -15,13 +15,21 @@
   initial-value: transparent;
 }
 
+/* Shared timing tokens — used by .interactive and other surfaces (e.g. table rows) */
+:root {
+  --interactive-duration: 150ms;
+  --interactive-easing: ease-in-out;
+}
+
 /* Base interactive surface */
 .interactive {
   @apply cursor-pointer select-none;
   transition:
-    background-color 150ms ease-in-out,
-    --interactive-foreground 150ms ease-in-out,
-    --interactive-foreground-icon 150ms ease-in-out;
+    background-color var(--interactive-duration) var(--interactive-easing),
+    --interactive-foreground var(--interactive-duration)
+      var(--interactive-easing),
+    --interactive-foreground-icon var(--interactive-duration)
+      var(--interactive-easing);
 }
 .interactive[data-disabled] {
   @apply cursor-not-allowed;

web/lib/opal/tsconfig.json

@@ -2,7 +2,14 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "paths": {
-      "@opal/*": ["./src/*"]
+      "@opal/*": ["./src/*"],
+      // TODO (@raunakab): Remove this once the table component migration is
+      // complete. The table internals still import app-layer modules (e.g.
+      // @/refresh-components/texts/Text, @/refresh-components/Popover) via the
+      // @/ alias. Without this entry the IDE cannot resolve those paths since
+      // opal's tsconfig only defines @opal/*. Once all @/ deps are replaced
+      // with opal-internal equivalents, this line should be deleted.
+      "@/*": ["../../src/*"]
     }
   },
   "include": ["src/**/*"],

web/src/app/admin/connector/[ccPairId]/IndexAttemptsTable.tsx

@@ -98,7 +98,14 @@ export function IndexAttemptsTable({
               isReindexInProgress ? "are being" : "were"
             } synced into the system.`;
             return (
-              <TableRow key={indexAttempt.id}>
+              <TableRow
+                key={indexAttempt.id}
+                className={
+                  indexAttempt.full_exception_trace
+                    ? "hover:bg-accent-background cursor-pointer relative select-none"
+                    : undefined
+                }
+              >
                 <TableCell>
                   {indexAttempt.time_started
                     ? localizeAndPrettify(indexAttempt.time_started)
@@ -146,46 +153,43 @@ export function IndexAttemptsTable({
                   </div>
                 </TableCell>
                 <TableCell>
-                  <div>
-                    {indexAttempt.status === "success" && (
+                  {indexAttempt.status === "success" && (
+                    <Text className="flex flex-wrap whitespace-normal">
+                      {"-"}
+                    </Text>
+                  )}
+
+                  {indexAttempt.status === "failed" &&
+                    indexAttempt.error_msg && (
                       <Text className="flex flex-wrap whitespace-normal">
-                        {"-"}
+                        {indexAttempt.error_msg}
                       </Text>
                     )}
-
-                    {indexAttempt.status === "failed" &&
-                      indexAttempt.error_msg && (
-                        <Text className="flex flex-wrap whitespace-normal">
-                          {indexAttempt.error_msg}
-                        </Text>
-                      )}
-
-                    {indexAttempt.full_exception_trace && (
-                      <div
-                        onClick={() => {
-                          setIndexAttemptTracePopupId(indexAttempt.id);
-                        }}
-                        className="mt-2 text-link cursor-pointer select-none"
-                      >
-                        View Full Trace
-                      </div>
-                    )}
-                  </div>
                 </TableCell>
+                <td className="w-0 p-0">
+                  {indexAttempt.full_exception_trace && (
+                    <button
+                      type="button"
+                      aria-label="View full trace"
+                      onClick={() =>
+                        setIndexAttemptTracePopupId(indexAttempt.id)
+                      }
+                      className="absolute w-full h-full left-0 top-0"
+                    />
+                  )}
+                </td>
               </TableRow>
             );
           })}
         </TableBody>
       </Table>
       {totalPages > 1 && (
-        <div className="mt-3 flex">
-          <div className="mx-auto">
-            <PageSelector
-              totalPages={totalPages}
-              currentPage={currentPage}
-              onPageChange={onPageChange}
-            />
-          </div>
+        <div className="flex flex-1 justify-center pt-3">
+          <PageSelector
+            totalPages={totalPages}
+            currentPage={currentPage}
+            onPageChange={onPageChange}
+          />
         </div>
       )}
     </>

web/src/app/admin/groups/page.tsx

@@ -0,0 +1 @@
+export { default } from "@/refresh-pages/admin/GroupsPage";

web/src/app/css/table.css

@@ -1,143 +0,0 @@
-/* ---------------------------------------------------------------------------
- * Table primitives — data-attribute driven styling
- * Follows the same pattern as card.css / line-item.css.
- * ------------------------------------------------------------------------- */
-
-/* ---- TableCell ---- */
-
-.tbl-cell[data-size="regular"] {
-  @apply px-1 py-0.5;
-}
-.tbl-cell[data-size="small"] {
-  @apply pl-0.5 pr-1.5 py-1.5;
-}
-
-.tbl-cell-inner[data-size="regular"] {
-  @apply h-10 px-1;
-}
-.tbl-cell-inner[data-size="small"] {
-  @apply h-6 px-0.5;
-}
-
-/* ---- TableHead ---- */
-
-.table-head {
-  @apply relative sticky top-0 z-20;
-  background: var(--table-header-bg, transparent);
-}
-.table-head[data-size="regular"] {
-  @apply px-2 py-1;
-}
-.table-head[data-size="small"] {
-  @apply p-1.5;
-}
-.table-head[data-bottom-border] {
-  @apply border-b border-transparent hover:border-border-03;
-}
-
-/* Inner text wrapper */
-.table-head[data-size="regular"] .table-head-label {
-  @apply py-2 px-0.5;
-}
-.table-head[data-size="small"] .table-head-label {
-  @apply py-1;
-}
-
-/* Sort button wrapper */
-.table-head[data-size="regular"] .table-head-sort {
-  @apply py-1.5;
-}
-
-/* ---- TableRow ---- */
-
-.tbl-row > td {
-  @apply bg-background-tint-00;
-}
-
-.tbl-row[data-variant="table"] > td {
-  @apply border-b border-border-01;
-}
-
-.tbl-row[data-variant="list"] > td {
-  @apply bg-clip-padding border-y-[4px] border-x-0 border-transparent;
-}
-.tbl-row[data-variant="list"] > td:first-child {
-  @apply rounded-l-12;
-}
-.tbl-row[data-variant="list"] > td:last-child {
-  @apply rounded-r-12;
-}
-
-/* When a drag handle is present the second-to-last td gets the rounding */
-.tbl-row[data-variant="list"][data-drag-handle] > td:nth-last-child(2) {
-  @apply rounded-r-12;
-}
-.tbl-row[data-variant="list"][data-drag-handle] > td:last-child {
-  border-radius: 0;
-}
-
-/* ---- Row states (list variant) ---- */
-
-.tbl-row[data-variant="list"]:hover > td {
-  @apply bg-background-tint-02;
-}
-.tbl-row[data-variant="list"]:focus-visible > td,
-.tbl-row[data-variant="list"]:has(:focus-visible) > td {
-  @apply bg-action-link-01;
-}
-
-.tbl-row[data-disabled] {
-  @apply pointer-events-none;
-}
-
-/* ---- Row states (table variant) ---- */
-
-.tbl-row[data-variant="table"]:hover > td {
-  @apply bg-background-tint-02;
-}
-.tbl-row[data-variant="table"]:focus-visible > td,
-.tbl-row[data-variant="table"]:has(:focus-visible) > td {
-  @apply bg-action-link-01;
-}
-
-/* Suppress default focus ring on rows — the row bg is the indicator */
-.tbl-row:focus,
-.tbl-row:focus-visible {
-  outline: none;
-}
-
-/* ---- QualifierContainer ---- */
-
-.tbl-qualifier[data-type="head"] {
-  @apply w-px whitespace-nowrap py-1 sticky top-0 z-20;
-  background: var(--table-header-bg, transparent);
-}
-.tbl-qualifier[data-type="head"][data-size="small"] {
-  @apply py-0.5;
-}
-
-.tbl-qualifier[data-type="cell"] {
-  @apply w-px whitespace-nowrap py-1 pl-1;
-}
-.tbl-qualifier[data-type="cell"][data-size="small"] {
-  @apply py-0.5 pl-0.5;
-}
-
-/* ---- ActionsContainer ---- */
-
-.tbl-actions {
-  @apply sticky right-0 w-px whitespace-nowrap;
-}
-.tbl-actions[data-type="head"] {
-  @apply z-30 sticky top-0;
-  background: var(--table-header-bg, transparent);
-}
-
-/* ---- Footer ---- */
-
-.table-footer[data-size="regular"] {
-  @apply min-h-[2.75rem];
-}
-.table-footer[data-size="small"] {
-  @apply min-h-[2.25rem];
-}

web/src/app/ee/admin/groups2/page.tsx

@@ -0,0 +1 @@
+export { default } from "@/refresh-pages/admin/GroupsPage";

web/src/app/globals.css

@@ -16,7 +16,6 @@
 @import "css/sizes.css";
 @import "css/square-button.css";
 @import "css/switch.css";
-@import "css/table.css";
 @import "css/z-index.css";
 
 /* KH Teka Font */

web/src/interfaces/llm.ts

@@ -123,6 +123,9 @@ export interface LLMProviderFormProps {
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
 
+  /** The current default model name for this provider (from the global default). */
+  defaultModelName?: string;
+
   // Onboarding-specific (only when variant === "onboarding")
   onboardingState?: OnboardingState;
   onboardingActions?: OnboardingActions;

web/src/refresh-components/Modal.tsx

@@ -451,13 +451,19 @@ const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
     );
 
     return (
-      <Section ref={ref} padding={1} alignItems="start" height="fit" {...props}>
+      <Section
+        ref={ref}
+        padding={0.5}
+        alignItems="start"
+        height="fit"
+        {...props}
+      >
         <Section
           flexDirection="row"
           justifyContent="between"
           alignItems="start"
           gap={0}
-          padding={0}
+          padding={0.5}
         >
           <div className="relative w-full">
             {/* Close button is absolutely positioned because:
@@ -485,7 +491,6 @@ const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
             </DialogPrimitive.Title>
           </div>
         </Section>
-
         {children}
       </Section>
     );

web/src/refresh-components/Separator.tsx

@@ -9,6 +9,8 @@ export interface SeparatorProps
   noPadding?: boolean;
   /** Custom horizontal padding in rem. Overrides the default padding. */
   paddingXRem?: number;
+  /** Custom vertical padding in rem. Overrides the default padding. */
+  paddingYRem?: number;
 }
 
 /**
@@ -37,7 +39,7 @@ const Separator = React.forwardRef(
     {
       noPadding,
       paddingXRem,
-
+      paddingYRem,
       className,
       orientation = "horizontal",
       decorative = true,
@@ -56,6 +58,12 @@ const Separator = React.forwardRef(
                 paddingRight: `${paddingXRem}rem`,
               }
             : {}),
+          ...(paddingYRem != null
+            ? {
+                paddingTop: `${paddingYRem}rem`,
+                paddingBottom: `${paddingYRem}rem`,
+              }
+            : {}),
         }}
         className={cn(
           isHorizontal ? "w-full" : "h-full",

web/src/refresh-components/modals/MemoriesModal.tsx

@@ -112,9 +112,11 @@ function MemoryItem({
             />
           </Disabled>
         </Section>
-        {isFocused && (
+        <div
+          className={isFocused ? "visible" : "invisible h-0 overflow-hidden"}
+        >
           <CharacterCount value={memory.content} limit={MAX_MEMORY_LENGTH} />
-        )}
+        </div>
       </Section>
     </div>
   );

web/src/refresh-components/table/README.md

@@ -1,462 +0,0 @@
-# DataTable
-
-Config-driven table built on [TanStack Table](https://tanstack.com/table). Handles column sizing (weight-based proportional distribution), drag-and-drop row reordering, pagination, row selection, column visibility, and sorting out of the box.
-
-## Quick Start
-
-```tsx
-import DataTable from "@/refresh-components/table/DataTable";
-import { createTableColumns } from "@/refresh-components/table/columns";
-
-interface Person {
-  name: string;
-  email: string;
-  role: string;
-}
-
-// Define columns at module scope (stable reference, no re-renders)
-const tc = createTableColumns<Person>();
-const columns = [
-  tc.qualifier(),
-  tc.column("name", { header: "Name", weight: 30, minWidth: 120 }),
-  tc.column("email", { header: "Email", weight: 40, minWidth: 150 }),
-  tc.column("role", { header: "Role", weight: 30, minWidth: 80 }),
-  tc.actions(),
-];
-
-function PeopleTable({ data }: { data: Person[] }) {
-  return (
-    <DataTable
-      data={data}
-      columns={columns}
-      pageSize={10}
-      footer={{ mode: "selection" }}
-    />
-  );
-}
-```
-
-## Column Builder API
-
-`createTableColumns<TData>()` returns a typed builder with four methods. Each returns an `OnyxColumnDef<TData>` that you pass to the `columns` prop.
-
-### `tc.qualifier(config?)`
-
-Leading column for avatars, icons, images, or checkboxes.
-
-| Option              | Type                                                              | Default    | Description                                   |
-| ------------------- | ----------------------------------------------------------------- | ---------- | --------------------------------------------- |
-| `content`           | `"simple" \| "icon" \| "image" \| "avatar-icon" \| "avatar-user"` | `"simple"` | Body row content type                         |
-| `headerContentType` | same as `content`                                                 | `"simple"` | Header row content type                       |
-| `getInitials`       | `(row: TData) => string`                                          | -          | Extract initials (for `"avatar-user"`)        |
-| `getIcon`           | `(row: TData) => IconFunctionComponent`                           | -          | Extract icon (for `"icon"` / `"avatar-icon"`) |
-| `getImageSrc`       | `(row: TData) => string`                                          | -          | Extract image src (for `"image"`)             |
-| `selectable`        | `boolean`                                                         | `true`     | Show selection checkboxes                     |
-| `header`            | `boolean`                                                         | `true`     | Render qualifier content in the header        |
-
-Width is fixed: 56px at `"regular"` size, 40px at `"small"`.
-
-```ts
-tc.qualifier({
-  content: "avatar-user",
-  getInitials: (row) => row.initials,
-});
-```
-
-### `tc.column(accessor, config)`
-
-Data column with sorting, resizing, and hiding. The `accessor` is a type-safe deep key into `TData`.
-
-| Option           | Type                                               | Default                 | Description                      |
-| ---------------- | -------------------------------------------------- | ----------------------- | -------------------------------- |
-| `header`         | `string`                                           | **required**            | Column header label              |
-| `cell`           | `(value: TValue, row: TData) => ReactNode`         | renders value as string | Custom cell renderer             |
-| `enableSorting`  | `boolean`                                          | `true`                  | Allow sorting                    |
-| `enableResizing` | `boolean`                                          | `true`                  | Allow column resize              |
-| `enableHiding`   | `boolean`                                          | `true`                  | Allow hiding via actions popover |
-| `icon`           | `(sorted: SortDirection) => IconFunctionComponent` | -                       | Override the sort indicator icon |
-| `weight`         | `number`                                           | `20`                    | Proportional width weight        |
-| `minWidth`       | `number`                                           | `50`                    | Minimum width in pixels          |
-
-```ts
-tc.column("email", {
-  header: "Email",
-  weight: 28,
-  minWidth: 150,
-  cell: (value) => <Content sizePreset="main-ui" variant="body" title={value} prominence="muted" />,
-})
-```
-
-### `tc.displayColumn(config)`
-
-Non-accessor column for custom content (e.g. computed values, action buttons per row).
-
-| Option         | Type                        | Default      | Description                            |
-| -------------- | --------------------------- | ------------ | -------------------------------------- |
-| `id`           | `string`                    | **required** | Unique column ID                       |
-| `header`       | `string`                    | -            | Optional header label                  |
-| `cell`         | `(row: TData) => ReactNode` | **required** | Cell renderer                          |
-| `width`        | `ColumnWidth`               | **required** | `{ weight, minWidth? }` or `{ fixed }` |
-| `enableHiding` | `boolean`                   | `true`       | Allow hiding                           |
-
-```ts
-tc.displayColumn({
-  id: "fullName",
-  header: "Full Name",
-  cell: (row) => `${row.firstName} ${row.lastName}`,
-  width: { weight: 25, minWidth: 100 },
-});
-```
-
-### `tc.actions(config?)`
-
-Fixed-width column rendered at the trailing edge. Houses column visibility and sorting popovers in the header.
-
-| Option                 | Type                        | Default | Description                                |
-| ---------------------- | --------------------------- | ------- | ------------------------------------------ |
-| `showColumnVisibility` | `boolean`                   | `true`  | Show the column visibility popover         |
-| `showSorting`          | `boolean`                   | `true`  | Show the sorting popover                   |
-| `sortingFooterText`    | `string`                    | -       | Footer text inside the sorting popover     |
-| `cell`                 | `(row: TData) => ReactNode` | -       | Row-level cell renderer for action buttons |
-
-Width is fixed: 88px at `"regular"`, 20px at `"small"`.
-
-```ts
-tc.actions({
-  sortingFooterText: "Everyone will see agents in this order.",
-});
-```
-
-Row-level actions — the `cell` callback receives the row data and renders content in each body row. Clicks inside the cell automatically call `stopPropagation`, so they won't trigger row selection.
-
-```tsx
-tc.actions({
-  cell: (row) => (
-    <div className="flex gap-x-1">
-      <IconButton icon={SvgPencil} onClick={() => openEdit(row.id)} />
-      <IconButton icon={SvgTrash} onClick={() => confirmDelete(row.id)} />
-    </div>
-  ),
-});
-```
-
-## DataTable Props
-
-`DataTableProps<TData>`:
-
-| Prop                      | Type                              | Default                                       | Description                                                                                            |
-| ------------------------- | --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `data`                    | `TData[]`                         | **required**                                  | Row data                                                                                               |
-| `columns`                 | `OnyxColumnDef<TData>[]`          | **required**                                  | Columns from `createTableColumns()`                                                                    |
-| `pageSize`                | `number`                          | `10` (with footer) or `data.length` (without) | Rows per page. `Infinity` disables pagination                                                          |
-| `initialSorting`          | `SortingState`                    | `[]`                                          | TanStack sorting state                                                                                 |
-| `initialColumnVisibility` | `VisibilityState`                 | `{}`                                          | Map of column ID to `false` to hide initially                                                          |
-| `draggable`               | `DataTableDraggableConfig<TData>` | -                                             | Enable drag-and-drop (see below)                                                                       |
-| `footer`                  | `DataTableFooterConfig`           | -                                             | Footer mode (see below)                                                                                |
-| `size`                    | `"regular" \| "small"`            | `"regular"`                                   | Table density variant                                                                                  |
-| `onRowClick`              | `(row: TData) => void`            | toggles selection                             | Called on row click, replaces default selection toggle                                                 |
-| `height`                  | `number \| string`                | -                                             | Max height for scrollable body (header stays pinned). `300` or `"50vh"`                                |
-| `headerBackground`        | `string`                          | -                                             | CSS color for the sticky header (prevents content showing through)                                     |
-| `searchTerm`              | `string`                          | -                                             | Search term for client-side global text filtering (case-insensitive match across all accessor columns) |
-| `serverSide`              | `ServerSideConfig`                | -                                             | Enable server-side mode for manual pagination, sorting, and filtering ([see below](#server-side-mode)) |
-
-## Footer Config
-
-The `footer` prop accepts a discriminated union on `mode`.
-
-### Selection mode
-
-For tables with selectable rows. Shows a selection message + count pagination.
-
-```ts
-footer={{
-  mode: "selection",
-  multiSelect: true,        // default true
-  onView: () => { ... },    // optional "View" button
-  onClear: () => { ... },   // optional "Clear" button (falls back to default clearSelection)
-}}
-```
-
-### Summary mode
-
-For read-only tables. Shows "Showing X~Y of Z" + list pagination.
-
-```ts
-footer={{ mode: "summary" }}
-```
-
-## Draggable Config
-
-Enable drag-and-drop row reordering. DnD is automatically disabled when column sorting is active.
-
-```ts
-<DataTable
-  data={items}
-  columns={columns}
-  draggable={{
-    getRowId: (row) => row.id,
-    onReorder: (ids, changedOrders) => {
-      // ids: new ordered array of all row IDs
-      // changedOrders: { [id]: newIndex } for rows that moved
-      setItems(ids.map((id) => items.find((r) => r.id === id)!));
-    },
-  }}
-/>
-```
-
-| Option      | Type                                                                              | Description                              |
-| ----------- | --------------------------------------------------------------------------------- | ---------------------------------------- |
-| `getRowId`  | `(row: TData) => string`                                                          | Extract a unique string ID from each row |
-| `onReorder` | `(ids: string[], changedOrders: Record<string, number>) => void \| Promise<void>` | Called after a successful reorder        |
-
-## Server-Side Mode
-
-Pass the `serverSide` prop to switch from client-side to server-side pagination, sorting, and filtering. In this mode `data` should contain **only the current page slice** — TanStack operates with `manualPagination`, `manualSorting`, and `manualFiltering` enabled. Drag-and-drop is automatically disabled.
-
-### `ServerSideConfig`
-
-| Prop                 | Type                                            | Description                                                                         |
-| -------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `totalItems`         | `number`                                        | Total row count from the server, used to compute page count                         |
-| `isLoading`          | `boolean`                                       | Shows a loading overlay (opacity + pointer-events-none) while data is being fetched |
-| `onSortingChange`    | `(sorting: SortingState) => void`               | Fired when the user clicks a column header                                          |
-| `onPaginationChange` | `(pageIndex: number, pageSize: number) => void` | Fired on page navigation and on automatic resets from sort/search changes           |
-| `onSearchTermChange` | `(searchTerm: string) => void`                  | Fired when the `searchTerm` prop changes                                            |
-
-### Callback contract
-
-The callbacks fire in a predictable order:
-
-- **Sort change** — `onSortingChange` fires first, then the page resets to 0 and `onPaginationChange(0, pageSize)` fires.
-- **Page navigation** — only `onPaginationChange` fires.
-- **Search change** — `onSearchTermChange` fires, and the page resets to 0. `onPaginationChange` only fires if the page was actually on a non-zero page. When already on page 0, `searchTerm` drives the re-fetch independently (e.g. via your SWR key) — no `onPaginationChange` is needed.
-
-Your data-fetching layer should include `searchTerm` in its fetch dependencies (e.g. SWR key) so that search changes trigger re-fetches regardless of pagination state.
-
-### Full example
-
-```tsx
-import { useState } from "react";
-import useSWR from "swr";
-import type { SortingState } from "@tanstack/react-table";
-import DataTable from "@/refresh-components/table/DataTable";
-import { createTableColumns } from "@/refresh-components/table/columns";
-import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-}
-
-const tc = createTableColumns<User>();
-const columns = [
-  tc.qualifier(),
-  tc.column("name", { header: "Name", weight: 40, minWidth: 120 }),
-  tc.column("email", { header: "Email", weight: 60, minWidth: 150 }),
-  tc.actions(),
-];
-
-function UsersTable() {
-  const [searchTerm, setSearchTerm] = useState("");
-  const [sorting, setSorting] = useState<SortingState>([]);
-  const [pageIndex, setPageIndex] = useState(0);
-  const [pageSize, setPageSize] = useState(10);
-
-  const { data: response, isLoading } = useSWR(
-    ["/api/users", sorting, pageIndex, pageSize, searchTerm],
-    ([url, sorting, pageIndex, pageSize, searchTerm]) =>
-      fetch(
-        `${url}?` +
-          new URLSearchParams({
-            page: String(pageIndex),
-            size: String(pageSize),
-            search: searchTerm,
-            ...(sorting[0] && {
-              sortBy: sorting[0].id,
-              sortDir: sorting[0].desc ? "desc" : "asc",
-            }),
-          })
-      ).then((r) => r.json())
-  );
-
-  return (
-    <div className="space-y-4">
-      <InputTypeIn
-        value={searchTerm}
-        onChange={(e) => setSearchTerm(e.target.value)}
-        placeholder="Search users..."
-      />
-      <DataTable
-        data={response?.items ?? []}
-        columns={columns}
-        getRowId={(row) => row.id}
-        searchTerm={searchTerm}
-        pageSize={pageSize}
-        footer={{ mode: "summary" }}
-        serverSide={{
-          totalItems: response?.total ?? 0,
-          isLoading,
-          onSortingChange: setSorting,
-          onPaginationChange: (idx, size) => {
-            setPageIndex(idx);
-            setPageSize(size);
-          },
-          onSearchTermChange: () => {
-            // search state is already managed above via searchTerm prop;
-            // this callback is useful for analytics or debouncing
-          },
-        }}
-      />
-    </div>
-  );
-}
-```
-
-## Sizing
-
-The `size` prop (`"regular"` or `"small"`) affects:
-
-- Qualifier column width (56px vs 40px)
-- Actions column width (88px vs 20px)
-- Footer text styles and pagination size
-- All child components via `TableSizeContext`
-
-Column widths can be responsive to size using a function:
-
-```ts
-// In types.ts, width accepts:
-width: ColumnWidth | ((size: TableSize) => ColumnWidth);
-
-// Example (this is what qualifier/actions use internally):
-width: (size) => (size === "small" ? { fixed: 40 } : { fixed: 56 });
-```
-
-### Width system
-
-Data columns use **weight-based proportional distribution**. A column with `weight: 40` gets twice the space of one with `weight: 20`. When the container is narrower than the sum of `minWidth` values, columns clamp to their minimums.
-
-Fixed columns (`{ fixed: N }`) take exactly N pixels and don't participate in proportional distribution.
-
-Resizing uses **splitter semantics**: dragging a column border grows that column and shrinks its neighbor by the same amount, keeping total width constant.
-
-## Advanced Examples
-
-### Scrollable table with pinned header
-
-```tsx
-<DataTable
-  data={allRows}
-  columns={columns}
-  height={300}
-  headerBackground="var(--background-tint-00)"
-/>
-```
-
-### Hidden columns on load
-
-```tsx
-<DataTable
-  data={data}
-  columns={columns}
-  initialColumnVisibility={{ department: false, joinDate: false }}
-  footer={{ mode: "selection" }}
-/>
-```
-
-### Icon-based data column
-
-```tsx
-const STATUS_ICONS = {
-  active: SvgCheckCircle,
-  pending: SvgClock,
-  inactive: SvgAlertCircle,
-} as const;
-
-tc.column("status", {
-  header: "Status",
-  weight: 14,
-  minWidth: 80,
-  cell: (value) => (
-    <Content
-      sizePreset="main-ui"
-      variant="body"
-      icon={STATUS_ICONS[value]}
-      title={value.charAt(0).toUpperCase() + value.slice(1)}
-    />
-  ),
-});
-```
-
-### Non-selectable qualifier with icons
-
-```ts
-tc.qualifier({
-  content: "icon",
-  getIcon: (row) => row.icon,
-  selectable: false,
-  header: false,
-});
-```
-
-### Small variant in a bordered container
-
-```tsx
-<div className="border border-border-01 rounded-lg overflow-hidden">
-  <DataTable
-    data={data}
-    columns={columns}
-    size="small"
-    pageSize={10}
-    footer={{ mode: "selection" }}
-  />
-</div>
-```
-
-### Server-side pagination
-
-Minimal wiring for server-side mode — manage sorting/pagination state externally and pass the current page slice as `data`.
-
-```tsx
-<DataTable
-  data={currentPageRows}
-  columns={columns}
-  getRowId={(row) => row.id}
-  searchTerm={searchTerm}
-  pageSize={pageSize}
-  footer={{ mode: "summary" }}
-  serverSide={{
-    totalItems: totalCount,
-    isLoading,
-    onSortingChange: setSorting,
-    onPaginationChange: (idx, size) => {
-      setPageIndex(idx);
-      setPageSize(size);
-    },
-    onSearchTermChange: (term) => setSearchTerm(term),
-  }}
-/>
-```
-
-### Custom row click handler
-
-```tsx
-<DataTable
-  data={data}
-  columns={columns}
-  onRowClick={(row) => router.push(`/users/${row.id}`)}
-/>
-```
-
-## Source Files
-
-| File                        | Purpose                          |
-| --------------------------- | -------------------------------- |
-| `DataTable.tsx`             | Main component                   |
-| `columns.ts`                | `createTableColumns` builder     |
-| `types.ts`                  | All TypeScript interfaces        |
-| `hooks/useDataTable.ts`     | TanStack table wrapper hook      |
-| `hooks/useColumnWidths.ts`  | Weight-based width system        |
-| `hooks/useDraggableRows.ts` | DnD hook (`@dnd-kit`)            |
-| `Footer.tsx`                | Selection / Summary footer modes |
-| `TableSizeContext.tsx`      | Size context provider            |

web/src/refresh-components/table/Table.stories.tsx

@@ -1,281 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import * as TooltipPrimitive from "@radix-ui/react-tooltip";
-import Table from "./Table";
-import TableHeader from "./TableHeader";
-import TableBody from "./TableBody";
-import TableRow from "./TableRow";
-import TableHead from "./TableHead";
-import TableCell from "./TableCell";
-import { TableSizeProvider } from "./TableSizeContext";
-import Text from "@/refresh-components/texts/Text";
-
-// ---------------------------------------------------------------------------
-// Meta
-// ---------------------------------------------------------------------------
-
-const meta: Meta<typeof Table> = {
-  title: "refresh-components/table/Table",
-  component: Table,
-  tags: ["autodocs"],
-  decorators: [
-    (Story) => (
-      <TooltipPrimitive.Provider>
-        <TableSizeProvider size="regular">
-          <div style={{ maxWidth: 800, padding: 16 }}>
-            <Story />
-          </div>
-        </TableSizeProvider>
-      </TooltipPrimitive.Provider>
-    ),
-  ],
-  parameters: {
-    layout: "padded",
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Table>;
-
-// ---------------------------------------------------------------------------
-// Sample data
-// ---------------------------------------------------------------------------
-
-const connectors = [
-  {
-    name: "Google Drive",
-    type: "Cloud Storage",
-    docs: 1_240,
-    status: "Active",
-  },
-  { name: "Confluence", type: "Wiki", docs: 856, status: "Active" },
-  { name: "Slack", type: "Messaging", docs: 3_102, status: "Syncing" },
-  { name: "Notion", type: "Wiki", docs: 412, status: "Paused" },
-  { name: "GitHub", type: "Code", docs: 2_890, status: "Active" },
-];
-
-// ---------------------------------------------------------------------------
-// Stories
-// ---------------------------------------------------------------------------
-
-/** All primitive table components composed together (Table, TableHeader, TableBody, TableRow, TableHead, TableCell). */
-export const ComposedPrimitives: Story = {
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200}>Connector</TableHead>
-          <TableHead width={150}>Type</TableHead>
-          <TableHead width={120} alignment="right">
-            Documents
-          </TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c) => (
-          <TableRow key={c.name}>
-            <TableCell>
-              <Text mainUiBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMuted text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMono text03>
-                {c.docs.toLocaleString()}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};
-
-/** Table rows with the "table" variant (bottom border instead of rounded corners). */
-export const TableVariantRows: Story = {
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200}>Connector</TableHead>
-          <TableHead width={150}>Type</TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c) => (
-          <TableRow key={c.name} variant="table">
-            <TableCell>
-              <Text mainUiBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMuted text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};
-
-/** Row with selected state highlighted. */
-export const SelectedRows: Story = {
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200}>Connector</TableHead>
-          <TableHead width={150}>Type</TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c, i) => (
-          <TableRow key={c.name} selected={i === 1 || i === 3}>
-            <TableCell>
-              <Text mainUiBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMuted text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};
-
-/** Sortable table headers with sort indicators. */
-export const SortableHeaders: Story = {
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200} sorted="ascending" onSort={() => {}}>
-            Connector
-          </TableHead>
-          <TableHead width={150} sorted="none" onSort={() => {}}>
-            Type
-          </TableHead>
-          <TableHead width={120} sorted="descending" onSort={() => {}}>
-            Documents
-          </TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c) => (
-          <TableRow key={c.name}>
-            <TableCell>
-              <Text mainUiBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMuted text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMono text03>
-                {c.docs.toLocaleString()}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};
-
-/** Small size variant with denser spacing. */
-export const SmallSize: Story = {
-  decorators: [
-    (Story) => (
-      <TooltipPrimitive.Provider>
-        <TableSizeProvider size="small">
-          <div style={{ maxWidth: 800, padding: 16 }}>
-            <Story />
-          </div>
-        </TableSizeProvider>
-      </TooltipPrimitive.Provider>
-    ),
-  ],
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200}>Connector</TableHead>
-          <TableHead width={150}>Type</TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c) => (
-          <TableRow key={c.name}>
-            <TableCell>
-              <Text secondaryBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text secondaryBody text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text secondaryBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};
-
-/** Disabled rows styling. */
-export const DisabledRows: Story = {
-  render: () => (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead width={200}>Connector</TableHead>
-          <TableHead width={150}>Type</TableHead>
-          <TableHead width={120}>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {connectors.map((c, i) => (
-          <TableRow key={c.name} disabled={i === 2 || i === 4}>
-            <TableCell>
-              <Text mainUiBody>{c.name}</Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiMuted text03>
-                {c.type}
-              </Text>
-            </TableCell>
-            <TableCell>
-              <Text mainUiBody>{c.status}</Text>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  ),
-};

web/src/refresh-components/table/Table.tsx

@@ -1,26 +0,0 @@
-import { cn } from "@/lib/utils";
-import type { WithoutStyles } from "@/types";
-
-interface TableProps
-  extends WithoutStyles<React.TableHTMLAttributes<HTMLTableElement>> {
-  ref?: React.Ref<HTMLTableElement>;
-  /** Explicit pixel width for the table (e.g. from `table.getTotalSize()`).
-   *  When provided the table uses exactly this width instead of stretching
-   *  to fill its container, which prevents `table-layout: fixed` from
-   *  redistributing extra space across columns on resize. */
-  width?: number;
-}
-
-function Table({ ref, width, ...props }: TableProps) {
-  return (
-    <table
-      ref={ref}
-      className={cn("border-separate border-spacing-0", "min-w-full")}
-      style={{ tableLayout: "fixed", width: width ?? undefined }}
-      {...props}
-    />
-  );
-}
-
-export default Table;
-export type { TableProps };

web/src/refresh-pages/AgentEditorPage.tsx

@@ -661,7 +661,7 @@ export default function AgentEditorPage({
     // Sharing
     shared_user_ids: existingAgent?.users?.map((user) => user.id) ?? [],
     shared_group_ids: existingAgent?.groups ?? [],
-    is_public: existingAgent?.is_public ?? true,
+    is_public: existingAgent?.is_public ?? false,
     label_ids: existingAgent?.labels?.map((l) => l.id) ?? [],
     featured: existingAgent?.featured ?? false,
   };

web/src/refresh-pages/admin/GroupsPage/GroupCard.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import type { UserGroup } from "@/lib/types";
+import { SvgChevronRight, SvgUserManage, SvgUsers } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
+import { Section } from "@/layouts/general-layouts";
+import Card from "@/refresh-components/cards/Card";
+import IconButton from "@/refresh-components/buttons/IconButton";
+import Text from "@/refresh-components/texts/Text";
+import { buildGroupDescription, formatMemberCount } from "./utils";
+
+interface GroupCardProps {
+  group: UserGroup;
+}
+
+function GroupCard({ group }: GroupCardProps) {
+  const isBasic = group.name === "Basic";
+  const isAdmin = group.name === "Admin";
+
+  return (
+    <Card padding={0.5}>
+      <ContentAction
+        icon={isAdmin ? SvgUserManage : SvgUsers}
+        title={group.name}
+        description={buildGroupDescription(group)}
+        sizePreset="main-content"
+        variant="section"
+        tag={isBasic ? { title: "Default" } : undefined}
+        rightChildren={
+          <Section flexDirection="row" alignItems="center">
+            <Text mainUiBody text03>
+              {formatMemberCount(group.users.length)}
+            </Text>
+            <IconButton icon={SvgChevronRight} tertiary tooltip="View group" />
+          </Section>
+        }
+      />
+    </Card>
+  );
+}
+
+export default GroupCard;

web/src/refresh-pages/admin/GroupsPage/GroupsList.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { useMemo } from "react";
+import type { UserGroup } from "@/lib/types";
+import Separator from "@/refresh-components/Separator";
+import GroupCard from "./GroupCard";
+import { isBuiltInGroup } from "./utils";
+import { Section } from "@/layouts/general-layouts";
+import { IllustrationContent } from "@opal/layouts";
+import SvgNoResult from "@opal/illustrations/no-result";
+
+interface GroupsListProps {
+  groups: UserGroup[];
+  searchQuery: string;
+}
+
+function GroupsList({ groups, searchQuery }: GroupsListProps) {
+  const filtered = useMemo(() => {
+    if (!searchQuery.trim()) return groups;
+    const q = searchQuery.toLowerCase();
+    return groups.filter((g) => g.name.toLowerCase().includes(q));
+  }, [groups, searchQuery]);
+
+  if (filtered.length === 0) {
+    return (
+      <IllustrationContent
+        illustration={SvgNoResult}
+        title="No groups found"
+        description={`No groups matching "${searchQuery}"`}
+      />
+    );
+  }
+
+  const builtInGroups = filtered.filter(isBuiltInGroup);
+  const customGroups = filtered.filter((g) => !isBuiltInGroup(g));
+
+  return (
+    <Section flexDirection="column" gap={0.5}>
+      {builtInGroups.map((group) => (
+        <GroupCard key={group.id} group={group} />
+      ))}
+
+      {builtInGroups.length > 0 && customGroups.length > 0 && (
+        <Separator paddingYRem={0.5} />
+      )}
+
+      {customGroups.map((group) => (
+        <GroupCard key={group.id} group={group} />
+      ))}
+    </Section>
+  );
+}
+
+export default GroupsList;

web/src/refresh-pages/admin/GroupsPage/index.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useState } from "react";
+import useSWR from "swr";
+import { SvgPlusCircle, SvgUsers } from "@opal/icons";
+import { Button } from "@opal/components";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import type { UserGroup } from "@/lib/types";
+import { USER_GROUP_URL } from "./svc";
+import GroupsList from "./GroupsList";
+import { Section } from "@/layouts/general-layouts";
+import { IllustrationContent } from "@opal/layouts";
+import SvgNoResult from "@opal/illustrations/no-result";
+
+function GroupsPage() {
+  const [searchQuery, setSearchQuery] = useState("");
+
+  const {
+    data: groups,
+    error,
+    isLoading,
+  } = useSWR<UserGroup[]>(USER_GROUP_URL, errorHandlingFetcher);
+
+  return (
+    <SettingsLayouts.Root>
+      {/* This is the sticky header for the groups page. It is used to display
+       * the groups page title and search input when scrolling down.
+       */}
+      <div className="sticky top-0 z-settings-header bg-background-tint-01">
+        <SettingsLayouts.Header icon={SvgUsers} title="Groups" separator />
+
+        <Section flexDirection="row" padding={1}>
+          <InputTypeIn
+            placeholder="Search groups..."
+            variant="internal"
+            value={searchQuery}
+            leftSearchIcon
+            onChange={(e) => setSearchQuery(e.target.value)}
+          />
+          <Button icon={SvgPlusCircle}>New Group</Button>
+        </Section>
+      </div>
+
+      <SettingsLayouts.Body>
+        {isLoading && <SimpleLoader />}
+
+        {error && (
+          <IllustrationContent
+            illustration={SvgNoResult}
+            title="Failed to load groups."
+            description="Please check the console for more details."
+          />
+        )}
+
+        {!isLoading && !error && groups && (
+          <GroupsList groups={groups} searchQuery={searchQuery} />
+        )}
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
+  );
+}
+
+export default GroupsPage;

web/src/refresh-pages/admin/GroupsPage/svc.ts

@@ -0,0 +1,5 @@
+/** API helpers for the Groups list page. */
+
+const USER_GROUP_URL = "/api/manage/admin/user-group";
+
+export { USER_GROUP_URL };

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

@@ -0,0 +1,57 @@
+import type { UserGroup } from "@/lib/types";
+
+/** Groups that are created by the system and cannot be deleted. */
+export const BUILT_IN_GROUP_NAMES = ["Basic", "Admin"] as const;
+
+export function isBuiltInGroup(group: UserGroup): boolean {
+  return (BUILT_IN_GROUP_NAMES as readonly string[]).includes(group.name);
+}
+
+/** Human-readable description for built-in groups. */
+const BUILT_IN_DESCRIPTIONS: Record<string, string> = {
+  Basic: "Default group for all users with basic permissions.",
+  Admin: "Built-in admin group with full access to manage all permissions.",
+};
+
+/**
+ * Build the description line(s) shown beneath the group name.
+ *
+ * Built-in groups use a fixed label.
+ * Custom groups list resource counts ("3 connectors · 2 document sets · 2 agents")
+ * or fall back to "No private connectors / document sets / agents".
+ */
+export function buildGroupDescription(group: UserGroup): string {
+  if (isBuiltInGroup(group)) {
+    return BUILT_IN_DESCRIPTIONS[group.name] ?? "";
+  }
+
+  const parts: string[] = [];
+  if (group.cc_pairs.length > 0) {
+    parts.push(
+      `${group.cc_pairs.length} connector${
+        group.cc_pairs.length !== 1 ? "s" : ""
+      }`
+    );
+  }
+  if (group.document_sets.length > 0) {
+    parts.push(
+      `${group.document_sets.length} document set${
+        group.document_sets.length !== 1 ? "s" : ""
+      }`
+    );
+  }
+  if (group.personas.length > 0) {
+    parts.push(
+      `${group.personas.length} agent${group.personas.length !== 1 ? "s" : ""}`
+    );
+  }
+
+  return parts.length > 0
+    ? parts.join(" · ")
+    : "No private connectors / document sets / agents";
+}
+
+/** Format the member count badge, e.g. "306 Members" or "1 Member". */
+export function formatMemberCount(count: number): string {
+  return `${count} ${count === 1 ? "Member" : "Members"}`;
+}

web/src/refresh-pages/admin/LLMConfigurationPage.tsx

@@ -148,12 +148,14 @@ interface ExistingProviderCardProps {
   provider: LLMProviderView;
   isDefault: boolean;
   isLastProvider: boolean;
+  defaultModelName?: string;
 }
 
 function ExistingProviderCard({
   provider,
   isDefault,
   isLastProvider,
+  defaultModelName,
 }: ExistingProviderCardProps) {
   const { mutate } = useSWRConfig();
   const [isOpen, setIsOpen] = useState(false);
@@ -230,7 +232,12 @@ function ExistingProviderCard({
               </Section>
             }
           />
-          {getModalForExistingProvider(provider, isOpen, setIsOpen)}
+          {getModalForExistingProvider(
+            provider,
+            isOpen,
+            setIsOpen,
+            defaultModelName
+          )}
         </Card>
       </Hoverable.Root>
     </>
@@ -446,6 +453,11 @@ export default function LLMConfigurationPage() {
                     provider={provider}
                     isDefault={defaultText?.provider_id === provider.id}
                     isLastProvider={sortedProviders.length === 1}
+                    defaultModelName={
+                      defaultText?.provider_id === provider.id
+                        ? defaultText.model_name
+                        : undefined
+                    }
                   />
                 ))}
               </div>

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

@@ -1,8 +1,7 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import DataTable from "@/refresh-components/table/DataTable";
-import { createTableColumns } from "@/refresh-components/table/columns";
+import { Table, createTableColumns } from "@opal/components";
 import { Content } from "@opal/layouts";
 import { Button } from "@opal/components";
 import { SvgDownload } from "@opal/icons";
@@ -216,10 +215,11 @@ export default function UsersTable({
         roleCounts={roleCounts}
         statusCounts={statusCounts}
       />
-      <DataTable
+      <Table
         data={filteredUsers}
         columns={columns}
         getRowId={(row) => row.id ?? row.email}
+        qualifier="avatar"
         pageSize={PAGE_SIZE}
         searchTerm={searchTerm}
         emptyState={
@@ -230,7 +230,6 @@ export default function UsersTable({
           />
         }
         footer={{
-          mode: "summary",
           leftExtra: (
             <Button
               icon={SvgDownload}

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

@@ -8,11 +8,11 @@ import { useScimToken } from "@/hooks/useScimToken";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import useUserCounts from "@/hooks/useUserCounts";
 import { UserStatus } from "@/lib/types";
-import type { StatusFilter } from "./UsersPage/interfaces";
+import type { StatusFilter } from "./interfaces";
 
-import UsersSummary from "./UsersPage/UsersSummary";
-import UsersTable from "./UsersPage/UsersTable";
-import InviteUsersModal from "./UsersPage/InviteUsersModal";
+import UsersSummary from "./UsersSummary";
+import UsersTable from "./UsersTable";
+import InviteUsersModal from "./InviteUsersModal";
 
 // ---------------------------------------------------------------------------
 // Users page content

web/src/sections/modals/ShareAgentModal.test.tsx

@@ -0,0 +1,83 @@
+import React, { useEffect } from "react";
+import { render, screen, waitFor } from "@tests/setup/test-utils";
+import ShareAgentModal, { ShareAgentModalProps } from "./ShareAgentModal";
+import { useCreateModal } from "@/refresh-components/contexts/ModalContext";
+
+jest.mock("@/hooks/useShareableUsers", () => ({
+  __esModule: true,
+  default: jest.fn(() => ({ data: [] })),
+}));
+
+jest.mock("@/hooks/useShareableGroups", () => ({
+  __esModule: true,
+  default: jest.fn(() => ({ data: [] })),
+}));
+
+jest.mock("@/hooks/useAgents", () => ({
+  useAgent: jest.fn(() => ({ agent: null })),
+}));
+
+jest.mock("@/lib/hooks", () => ({
+  useLabels: jest.fn(() => ({
+    labels: [],
+    createLabel: jest.fn(),
+  })),
+}));
+
+function ModalHarness(props: ShareAgentModalProps) {
+  const modal = useCreateModal();
+
+  useEffect(() => {
+    modal.toggle(true);
+  }, [modal]);
+
+  return (
+    <modal.Provider>
+      <ShareAgentModal {...props} />
+    </modal.Provider>
+  );
+}
+
+function renderShareAgentModal(overrides: Partial<ShareAgentModalProps> = {}) {
+  const props: ShareAgentModalProps = {
+    userIds: [],
+    groupIds: [],
+    isPublic: false,
+    isFeatured: false,
+    labelIds: [],
+    ...overrides,
+  };
+
+  return render(<ModalHarness {...props} />);
+}
+
+describe("ShareAgentModal", () => {
+  it("defaults to Users & Groups when the agent is private", async () => {
+    renderShareAgentModal({ isPublic: false });
+
+    await waitFor(() =>
+      expect(
+        screen.getByRole("tab", { name: "Users & Groups" })
+      ).toHaveAttribute("data-state", "active")
+    );
+
+    expect(
+      screen.getByRole("tab", { name: "Your Organization" })
+    ).toHaveAttribute("data-state", "inactive");
+  });
+
+  it("defaults to Your Organization when the agent is public", async () => {
+    renderShareAgentModal({ isPublic: true });
+
+    await waitFor(() =>
+      expect(
+        screen.getByRole("tab", { name: "Your Organization" })
+      ).toHaveAttribute("data-state", "active")
+    );
+
+    expect(screen.getByRole("tab", { name: "Users & Groups" })).toHaveAttribute(
+      "data-state",
+      "inactive"
+    );
+  });
+});

web/src/sections/modals/llmConfig/AnthropicModal.tsx

@@ -35,6 +35,7 @@ export default function AnthropicModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -64,10 +65,15 @@ export default function AnthropicModal({
         default_model_name: DEFAULT_DEFAULT_MODEL_NAME,
       }
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? undefined,
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           DEFAULT_DEFAULT_MODEL_NAME,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

web/src/sections/modals/llmConfig/AzureModal.tsx

@@ -81,6 +81,7 @@ export default function AzureModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -109,7 +110,11 @@ export default function AzureModal({
         default_model_name: "",
       } as AzureModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         target_uri: buildTargetUri(existingLlmProvider),
       };

web/src/sections/modals/llmConfig/BedrockModal.tsx

@@ -315,6 +315,7 @@ export default function BedrockModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -351,7 +352,11 @@ export default function BedrockModal({
         },
       } as BedrockModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         custom_config: {
           AWS_REGION_NAME:
             (existingLlmProvider?.custom_config?.AWS_REGION_NAME as string) ??

web/src/sections/modals/llmConfig/CustomModal.tsx

@@ -197,6 +197,7 @@ export default function CustomModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
 }: LLMProviderFormProps) {
@@ -209,7 +210,11 @@ export default function CustomModal({
   const onClose = () => onOpenChange?.(false);
 
   const initialValues = {
-    ...buildDefaultInitialValues(existingLlmProvider),
+    ...buildDefaultInitialValues(
+      existingLlmProvider,
+      undefined,
+      defaultModelName
+    ),
     ...(isOnboarding ? buildOnboardingInitialValues() : {}),
     provider: existingLlmProvider?.provider ?? "",
     model_configurations: existingLlmProvider?.model_configurations.map(

web/src/sections/modals/llmConfig/LMStudioForm.tsx

@@ -192,6 +192,7 @@ export default function LMStudioForm({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -225,7 +226,11 @@ export default function LMStudioForm({
         },
       } as LMStudioFormValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
         custom_config: {
           LM_STUDIO_API_KEY:

web/src/sections/modals/llmConfig/LiteLLMProxyModal.tsx

@@ -159,6 +159,7 @@ export default function LiteLLMProxyModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -190,7 +191,11 @@ export default function LiteLLMProxyModal({
         default_model_name: "",
       } as LiteLLMProxyModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
       };

web/src/sections/modals/llmConfig/OllamaModal.tsx

@@ -212,6 +212,7 @@ export default function OllamaModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -244,7 +245,11 @@ export default function OllamaModal({
         },
       } as OllamaModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
         custom_config: {
           OLLAMA_API_KEY:

web/src/sections/modals/llmConfig/OpenAIModal.tsx

@@ -35,6 +35,7 @@ export default function OpenAIModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -63,9 +64,14 @@ export default function OpenAIModal({
         default_model_name: DEFAULT_DEFAULT_MODEL_NAME,
       }
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           DEFAULT_DEFAULT_MODEL_NAME,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

web/src/sections/modals/llmConfig/OpenRouterModal.tsx

@@ -158,6 +158,7 @@ export default function OpenRouterModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -189,7 +190,11 @@ export default function OpenRouterModal({
         default_model_name: "",
       } as OpenRouterModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
       };

web/src/sections/modals/llmConfig/VertexAIModal.tsx

@@ -48,6 +48,7 @@ export default function VertexAIModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -80,8 +81,13 @@ export default function VertexAIModal({
         },
       } as VertexAIModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           VERTEXAI_DEFAULT_MODEL,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

web/src/sections/modals/llmConfig/getModal.tsx

@@ -22,9 +22,15 @@ function detectIfRealOpenAIProvider(provider: LLMProviderView) {
 export function getModalForExistingProvider(
   provider: LLMProviderView,
   open?: boolean,
-  onOpenChange?: (open: boolean) => void
+  onOpenChange?: (open: boolean) => void,
+  defaultModelName?: string
 ) {
-  const props = { existingLlmProvider: provider, open, onOpenChange };
+  const props = {
+    existingLlmProvider: provider,
+    open,
+    onOpenChange,
+    defaultModelName,
+  };
 
   switch (provider.provider) {
     case LLMProviderName.OPENAI:

web/src/sections/modals/llmConfig/utils.ts

@@ -12,9 +12,11 @@ export const LLM_FORM_CLASS_NAME = "flex flex-col gap-y-4 items-stretch mt-6";
 
 export const buildDefaultInitialValues = (
   existingLlmProvider?: LLMProviderView,
-  modelConfigurations?: ModelConfiguration[]
+  modelConfigurations?: ModelConfiguration[],
+  currentDefaultModelName?: string
 ) => {
   const defaultModelName =
+    currentDefaultModelName ??
     existingLlmProvider?.model_configurations?.[0]?.name ??
     modelConfigurations?.[0]?.name ??
     "";

web/tests/e2e/admin/code-interpreter/code_interpreter.spec.ts

@@ -58,7 +58,7 @@ async function mockCodeInterpreterApi(
  */
 function getDisconnectIconButton(page: Page) {
   return page
-    .locator("button:has(.opal-button):not(:has(.opal-button-label))")
+    .locator("button:has(.interactive-foreground-icon):not(:has(span))")
     .first();
 }
 

web/tests/e2e/mcp/mcp_oauth_flow.spec.ts

@@ -1860,6 +1860,9 @@ test.describe("MCP OAuth flows", () => {
       toolName: TOOL_NAMES.admin,
       logStep,
     });
+    const createdAgent = await adminApiClient.getAssistant(agentId);
+    expect(createdAgent.is_public).toBe(false);
+    logStep("Verified newly created agent is private by default");
     const adminToolId = await fetchMcpToolIdByName(
       page,
       serverId,
@@ -1899,6 +1902,13 @@ test.describe("MCP OAuth flows", () => {
     ).toBeVisible({ timeout: 15000 });
     logStep("Verified MCP server card is still visible on actions page");
 
+    await adminApiClient.updateAgentSharing(agentId, {
+      isPublic: true,
+      userIds: createdAgent.users.map((user) => user.id),
+      groupIds: createdAgent.groups,
+    });
+    logStep("Published agent explicitly for end-user MCP flow");
+
     adminArtifacts = {
       serverId,
       serverName,