feat(providers): allow deleting all types of providers (#9625)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

.greptile/config.json

@@ -0,0 +1,64 @@
+{
+    "labels": [],
+    "comment": "",
+    "fixWithAI": true,
+    "hideFooter": false,
+    "strictness": 3,
+    "statusCheck": true,
+    "commentTypes": [
+      "logic",
+      "syntax",
+      "style"
+    ],
+    "instructions": "",
+    "disabledLabels": [],
+    "excludeAuthors": [
+      "dependabot[bot]",
+      "renovate[bot]"
+    ],
+    "ignoreKeywords": "",
+    "ignorePatterns": "",
+    "includeAuthors": [],
+    "summarySection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "excludeBranches": [],
+    "fileChangeLimit": 300,
+    "includeBranches": [],
+    "includeKeywords": "",
+    "triggerOnUpdates": true,
+    "updateExistingSummaryComment": true,
+    "updateSummaryOnly": false,
+    "issuesTableSection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "statusCommentsEnabled": true,
+    "confidenceScoreSection": {
+      "included": true,
+      "collapsible": false
+    },
+    "sequenceDiagramSection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "shouldUpdateDescription": false,
+    "rules": [
+      {
+        "scope": ["web/**"],
+        "rule": "In Onyx's Next.js app, the `app/ee/admin/` directory is a filesystem convention for Enterprise Edition route overrides — it does NOT add an `/ee/` prefix to the URL. Both `app/admin/groups/page.tsx` and `app/ee/admin/groups/page.tsx` serve the same URL `/admin/groups`. Hardcoded `/admin/...` paths in router.push() calls are correct and do NOT break EE deployments. Do not flag hardcoded admin paths as bugs."
+      },
+      {
+        "scope": ["web/**"],
+        "rule": "In Onyx, each API key creates a unique user row in the database with a unique `user_id` (UUID). There is a 1:1 mapping between API keys and their backing user records. Multiple API keys do NOT share the same `user_id`. Do not flag potential duplicate row IDs when using `user_id` from API key descriptors."
+      },
+      {
+        "scope": ["backend/**/*.py"],
+        "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"detail\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
+      }
+    ]
+}

.greptile/files.json

@@ -0,0 +1,57 @@
+[
+  {
+    "scope": [],
+    "path": "contributing_guides/best_practices.md",
+    "description": "Best practices for contributing to the codebase"
+  },
+  {
+    "scope": ["web/**"],
+    "path": "web/AGENTS.md",
+    "description": "Frontend coding standards for the web directory"
+  },
+  {
+    "scope": ["web/**"],
+    "path": "web/tests/README.md",
+    "description": "Frontend testing guide and conventions"
+  },
+  {
+    "scope": ["web/**"],
+    "path": "web/CLAUDE.md",
+    "description": "Single source of truth for frontend coding standards"
+  },
+  {
+    "scope": ["web/**"],
+    "path": "web/lib/opal/README.md",
+    "description": "Opal component library usage guide"
+  },
+  {
+    "scope": ["backend/**"],
+    "path": "backend/tests/README.md",
+    "description": "Backend testing guide covering all 4 test types, fixtures, and conventions"
+  },
+  {
+    "scope": ["backend/onyx/connectors/**"],
+    "path": "backend/onyx/connectors/README.md",
+    "description": "Connector development guide covering design, interfaces, and required changes"
+  },
+  {
+    "scope": [],
+    "path": "CLAUDE.md",
+    "description": "Project instructions and coding standards"
+  },
+  {
+    "scope": [],
+    "path": "backend/alembic/README.md",
+    "description": "Migration guidance, including multi-tenant migration behavior"
+  },
+  {
+    "scope": [],
+    "path": "deployment/helm/charts/onyx/values-lite.yaml",
+    "description": "Lite deployment Helm values and service assumptions"
+  },
+  {
+    "scope": [],
+    "path": "deployment/docker_compose/docker-compose.onyx-lite.yml",
+    "description": "Lite deployment Docker Compose overlay and disabled service behavior"
+  }
+]

.greptile/rules.md

@@ -0,0 +1,29 @@
+# Greptile Review Rules
+
+## Type Annotations
+
+Use explicit type annotations for variables to enhance code clarity, especially when moving type hints around in the code.
+
+## Best Practices
+
+Use `contributing_guides/best_practices.md` as core review context. Prefer consistency with existing patterns, fix issues in code you touch, avoid tacking new features onto muddy interfaces, fail loudly instead of silently swallowing errors, keep code strictly typed, preserve clear state boundaries, remove duplicate or dead logic, break up overly long functions, avoid hidden import-time side effects, respect module boundaries, and favor correctness-by-construction over relying on callers to use an API correctly.
+
+## TODOs
+
+Whenever a TODO is added, there must always be an associated name or ticket with that TODO in the style of `TODO(name): ...` or `TODO(1234): ...`
+
+## Debugging Code
+
+Remove temporary debugging code before merging to production, especially tenant-specific debugging logs.
+
+## Hardcoded Booleans
+
+When hardcoding a boolean variable to a constant value, remove the variable entirely and clean up all places where it's used rather than just setting it to a constant.
+
+## Multi-tenant vs Single-tenant
+
+Code changes must consider both multi-tenant and single-tenant deployments. In multi-tenant mode, preserve tenant isolation, ensure tenant context is propagated correctly, and avoid assumptions that only hold for a single shared schema or globally shared state. In single-tenant mode, avoid introducing unnecessary tenant-specific requirements or cloud-only control-plane dependencies.
+
+## Full vs Lite Deployments
+
+Code changes must consider both regular Onyx deployments and Onyx lite deployments. Lite deployments disable the vector DB, Redis, model servers, and background workers by default, use PostgreSQL-backed cache/auth/file storage, and rely on the API server to handle background work. Do not assume those services are available unless the code path is explicitly limited to full deployments.

backend/alembic/versions/1d78c0ca7853_remove_voice_provider_deleted_column.py

@@ -0,0 +1,35 @@
+"""remove voice_provider deleted column
+
+Revision ID: 1d78c0ca7853
+Revises: a3f8b2c1d4e5
+Create Date: 2026-03-26 11:30:53.883127
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "1d78c0ca7853"
+down_revision = "a3f8b2c1d4e5"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Hard-delete any soft-deleted rows before dropping the column
+    op.execute("DELETE FROM voice_provider WHERE deleted = true")
+    op.drop_column("voice_provider", "deleted")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "voice_provider",
+        sa.Column(
+            "deleted",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )

backend/onyx/connectors/canvas/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+from onyx.connectors.cross_connector_utils.rate_limit_wrapper import (
+    rl_requests,
+)
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+
+logger = logging.getLogger(__name__)
+
+# Requests timeout in seconds.
+_CANVAS_CALL_TIMEOUT: int = 30
+_CANVAS_API_VERSION: str = "/api/v1"
+# Matches the "next" URL in a Canvas Link header, e.g.:
+#   <https://canvas.example.com/api/v1/courses?page=2>; rel="next"
+# Captures the URL inside the angle brackets.
+_NEXT_LINK_PATTERN: re.Pattern[str] = re.compile(r'<([^>]+)>;\s*rel="next"')
+
+
+_STATUS_TO_ERROR_CODE: dict[int, OnyxErrorCode] = {
+    401: OnyxErrorCode.CREDENTIAL_EXPIRED,
+    403: OnyxErrorCode.INSUFFICIENT_PERMISSIONS,
+    404: OnyxErrorCode.BAD_GATEWAY,
+    429: OnyxErrorCode.RATE_LIMITED,
+}
+
+
+def _error_code_for_status(status_code: int) -> OnyxErrorCode:
+    """Map an HTTP status code to the appropriate OnyxErrorCode.
+
+    Expects a >= 400 status code. Known codes (401, 403, 404, 429) are
+    mapped to specific error codes; all other codes (unrecognised 4xx
+    and 5xx) map to BAD_GATEWAY as unexpected upstream errors.
+    """
+    if status_code in _STATUS_TO_ERROR_CODE:
+        return _STATUS_TO_ERROR_CODE[status_code]
+    return OnyxErrorCode.BAD_GATEWAY
+
+
+class CanvasApiClient:
+    def __init__(
+        self,
+        bearer_token: str,
+        canvas_base_url: str,
+    ) -> None:
+        parsed_base = urlparse(canvas_base_url)
+        if not parsed_base.hostname:
+            raise ValueError("canvas_base_url must include a valid host")
+        if parsed_base.scheme != "https":
+            raise ValueError("canvas_base_url must use https")
+
+        self._bearer_token = bearer_token
+        self.base_url = (
+            canvas_base_url.rstrip("/").removesuffix(_CANVAS_API_VERSION)
+            + _CANVAS_API_VERSION
+        )
+        # Hostname is already validated above; reuse parsed_base instead
+        # of re-parsing.  Used by _parse_next_link to validate pagination URLs.
+        self._expected_host: str = parsed_base.hostname
+
+    def get(
+        self,
+        endpoint: str = "",
+        params: dict[str, Any] | None = None,
+        full_url: str | None = None,
+    ) -> tuple[Any, str | None]:
+        """Make a GET request to the Canvas API.
+
+        Returns a tuple of (json_body, next_url).
+        next_url is parsed from the Link header and is None if there are no more pages.
+        If full_url is provided, it is used directly (for following pagination links).
+
+        Security note: full_url must only be set to values returned by
+        ``_parse_next_link``, which validates the host against the configured
+        Canvas base URL.  Passing an arbitrary URL would leak the bearer token.
+        """
+        # full_url is used when following pagination (Canvas returns the
+        # next-page URL in the Link header).  For the first request we build
+        # the URL from the endpoint name instead.
+        url = full_url if full_url else self._build_url(endpoint)
+        headers = self._build_headers()
+
+        response = rl_requests.get(
+            url,
+            headers=headers,
+            params=params if not full_url else None,
+            timeout=_CANVAS_CALL_TIMEOUT,
+        )
+
+        try:
+            response_json = response.json()
+        except ValueError as e:
+            if response.status_code < 300:
+                raise OnyxError(
+                    OnyxErrorCode.BAD_GATEWAY,
+                    detail=f"Invalid JSON in Canvas response: {e}",
+                )
+            logger.warning(
+                "Failed to parse JSON from Canvas error response (status=%d): %s",
+                response.status_code,
+                e,
+            )
+            response_json = {}
+
+        if response.status_code >= 400:
+            # Try to extract the most specific error message from the
+            # Canvas response body.  Canvas uses three different shapes
+            # depending on the endpoint and error type:
+            default_error: str = response.reason or f"HTTP {response.status_code}"
+            error = default_error
+            if isinstance(response_json, dict):
+                # Shape 1: {"error": {"message": "Not authorized"}}
+                error_field = response_json.get("error")
+                if isinstance(error_field, dict):
+                    response_error = error_field.get("message", "")
+                    if response_error:
+                        error = response_error
+                # Shape 2: {"error": "Invalid access token"}
+                elif isinstance(error_field, str):
+                    error = error_field
+                # Shape 3: {"errors": [{"message": "..."}]}
+                # Used for validation errors.  Only use as fallback if
+                # we didn't already find a more specific message above.
+                if error == default_error:
+                    errors_list = response_json.get("errors")
+                    if isinstance(errors_list, list) and errors_list:
+                        first_error = errors_list[0]
+                        if isinstance(first_error, dict):
+                            msg = first_error.get("message", "")
+                            if msg:
+                                error = msg
+            raise OnyxError(
+                _error_code_for_status(response.status_code),
+                detail=error,
+                status_code_override=response.status_code,
+            )
+
+        next_url = self._parse_next_link(response.headers.get("Link", ""))
+        return response_json, next_url
+
+    def _parse_next_link(self, link_header: str) -> str | None:
+        """Extract the 'next' URL from a Canvas Link header.
+
+        Only returns URLs whose host matches the configured Canvas base URL
+        to prevent leaking the bearer token to arbitrary hosts.
+        """
+        expected_host = self._expected_host
+        for match in _NEXT_LINK_PATTERN.finditer(link_header):
+            url = match.group(1)
+            parsed_url = urlparse(url)
+            if parsed_url.hostname != expected_host:
+                raise OnyxError(
+                    OnyxErrorCode.BAD_GATEWAY,
+                    detail=(
+                        "Canvas pagination returned an unexpected host "
+                        f"({parsed_url.hostname}); expected {expected_host}"
+                    ),
+                )
+            if parsed_url.scheme != "https":
+                raise OnyxError(
+                    OnyxErrorCode.BAD_GATEWAY,
+                    detail=(
+                        "Canvas pagination link must use https, "
+                        f"got {parsed_url.scheme!r}"
+                    ),
+                )
+            return url
+        return None
+
+    def _build_headers(self) -> dict[str, str]:
+        """Return the Authorization header with the bearer token."""
+        return {"Authorization": f"Bearer {self._bearer_token}"}
+
+    def _build_url(self, endpoint: str) -> str:
+        """Build a full Canvas API URL from an endpoint path.
+
+        Assumes endpoint is non-empty (e.g. ``"courses"``, ``"announcements"``).
+        Only called on a first request, endpoint must be set for first request.
+        Verify endpoint exists in case of future changes where endpoint might be optional.
+        Leading slashes are stripped to avoid double-slash in the result.
+        self.base_url is already normalized with no trailing slash.
+        """
+        final_url = self.base_url
+        clean_endpoint = endpoint.lstrip("/")
+        if clean_endpoint:
+            final_url += "/" + clean_endpoint
+        return final_url

backend/onyx/connectors/canvas/connector.py

@@ -0,0 +1,74 @@
+from typing import Literal
+from typing import TypeAlias
+
+from pydantic import BaseModel
+
+from onyx.connectors.models import ConnectorCheckpoint
+
+
+class CanvasCourse(BaseModel):
+    id: int
+    name: str
+    course_code: str
+    created_at: str
+    workflow_state: str
+
+
+class CanvasPage(BaseModel):
+    page_id: int
+    url: str
+    title: str
+    body: str | None = None
+    created_at: str
+    updated_at: str
+    course_id: int
+
+
+class CanvasAssignment(BaseModel):
+    id: int
+    name: str
+    description: str | None = None
+    html_url: str
+    course_id: int
+    created_at: str
+    updated_at: str
+    due_at: str | None = None
+
+
+class CanvasAnnouncement(BaseModel):
+    id: int
+    title: str
+    message: str | None = None
+    html_url: str
+    posted_at: str | None = None
+    course_id: int
+
+
+CanvasStage: TypeAlias = Literal["pages", "assignments", "announcements"]
+
+
+class CanvasConnectorCheckpoint(ConnectorCheckpoint):
+    """Checkpoint state for resumable Canvas indexing.
+
+    Fields:
+        course_ids: Materialized list of course IDs to process.
+        current_course_index: Index into course_ids for current course.
+        stage: Which item type we're processing for the current course.
+        next_url: Pagination cursor within the current stage. None means
+            start from the first page; a URL means resume from that page.
+
+    Invariant:
+        If current_course_index is incremented, stage must be reset to
+        "pages" and next_url must be reset to None.
+    """
+
+    course_ids: list[int] = []
+    current_course_index: int = 0
+    stage: CanvasStage = "pages"
+    next_url: str | None = None
+
+    def advance_course(self) -> None:
+        """Move to the next course and reset within-course state."""
+        self.current_course_index += 1
+        self.stage = "pages"
+        self.next_url = None

backend/onyx/connectors/jira/connector.py

@@ -10,6 +10,7 @@ from datetime import timedelta
 from datetime import timezone
 from typing import Any
 
+import requests
 from jira import JIRA
 from jira.exceptions import JIRAError
 from jira.resources import Issue
@@ -239,29 +240,53 @@ def enhanced_search_ids(
     )
 
 
-def bulk_fetch_issues(
-    jira_client: JIRA, issue_ids: list[str], fields: str | None = None
-) -> list[Issue]:
-    # TODO: move away from this jira library if they continue to not support
-    # the endpoints we need. Using private fields is not ideal, but
-    # is likely fine for now since we pin the library version
+def _bulk_fetch_request(
+    jira_client: JIRA, issue_ids: list[str], fields: str | None
+) -> list[dict[str, Any]]:
+    """Raw POST to the bulkfetch endpoint. Returns the list of raw issue dicts."""
     bulk_fetch_path = jira_client._get_url("issue/bulkfetch")
-
     # Prepare the payload according to Jira API v3 specification
     payload: dict[str, Any] = {"issueIdsOrKeys": issue_ids}
-
     # Only restrict fields if specified, might want to explicitly do this in the future
     # to avoid reading unnecessary data
     payload["fields"] = fields.split(",") if fields else ["*all"]
 
+    resp = jira_client._session.post(bulk_fetch_path, json=payload)
+    return resp.json()["issues"]
+
+
+def bulk_fetch_issues(
+    jira_client: JIRA, issue_ids: list[str], fields: str | None = None
+) -> list[Issue]:
+    # TODO(evan): move away from this jira library if they continue to not support
+    # the endpoints we need. Using private fields is not ideal, but
+    # is likely fine for now since we pin the library version
+
     try:
-        response = jira_client._session.post(bulk_fetch_path, json=payload).json()
+        raw_issues = _bulk_fetch_request(jira_client, issue_ids, fields)
+    except requests.exceptions.JSONDecodeError:
+        if len(issue_ids) <= 1:
+            logger.exception(
+                f"Jira bulk-fetch response for issue(s) {issue_ids} could not "
+                f"be decoded as JSON (response too large or truncated)."
+            )
+            raise
+
+        mid = len(issue_ids) // 2
+        logger.warning(
+            f"Jira bulk-fetch JSON decode failed for batch of {len(issue_ids)} issues. "
+            f"Splitting into sub-batches of {mid} and {len(issue_ids) - mid}."
+        )
+        left = bulk_fetch_issues(jira_client, issue_ids[:mid], fields)
+        right = bulk_fetch_issues(jira_client, issue_ids[mid:], fields)
+        return left + right
     except Exception as e:
         logger.error(f"Error fetching issues: {e}")
-        raise e
+        raise
+
     return [
         Issue(jira_client._options, jira_client._session, raw=issue)
-        for issue in response["issues"]
+        for issue in raw_issues
     ]
 
 

backend/onyx/db/models.py

@@ -3135,8 +3135,6 @@ class VoiceProvider(Base):
     is_default_stt: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
     is_default_tts: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
 
-    deleted: Mapped[bool] = mapped_column(Boolean, default=False)
-
     time_created: Mapped[datetime.datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now()
     )

backend/onyx/db/voice.py

@@ -17,39 +17,30 @@ MAX_VOICE_PLAYBACK_SPEED = 2.0
 def fetch_voice_providers(db_session: Session) -> list[VoiceProvider]:
     """Fetch all voice providers."""
     return list(
-        db_session.scalars(
-            select(VoiceProvider)
-            .where(VoiceProvider.deleted.is_(False))
-            .order_by(VoiceProvider.name)
-        ).all()
+        db_session.scalars(select(VoiceProvider).order_by(VoiceProvider.name)).all()
     )
 
 
 def fetch_voice_provider_by_id(
-    db_session: Session, provider_id: int, include_deleted: bool = False
+    db_session: Session, provider_id: int
 ) -> VoiceProvider | None:
     """Fetch a voice provider by ID."""
-    stmt = select(VoiceProvider).where(VoiceProvider.id == provider_id)
-    if not include_deleted:
-        stmt = stmt.where(VoiceProvider.deleted.is_(False))
-    return db_session.scalar(stmt)
+    return db_session.scalar(
+        select(VoiceProvider).where(VoiceProvider.id == provider_id)
+    )
 
 
 def fetch_default_stt_provider(db_session: Session) -> VoiceProvider | None:
     """Fetch the default STT provider."""
     return db_session.scalar(
-        select(VoiceProvider)
-        .where(VoiceProvider.is_default_stt.is_(True))
-        .where(VoiceProvider.deleted.is_(False))
+        select(VoiceProvider).where(VoiceProvider.is_default_stt.is_(True))
     )
 
 
 def fetch_default_tts_provider(db_session: Session) -> VoiceProvider | None:
     """Fetch the default TTS provider."""
     return db_session.scalar(
-        select(VoiceProvider)
-        .where(VoiceProvider.is_default_tts.is_(True))
-        .where(VoiceProvider.deleted.is_(False))
+        select(VoiceProvider).where(VoiceProvider.is_default_tts.is_(True))
     )
 
 
@@ -58,9 +49,7 @@ def fetch_voice_provider_by_type(
 ) -> VoiceProvider | None:
     """Fetch a voice provider by type."""
     return db_session.scalar(
-        select(VoiceProvider)
-        .where(VoiceProvider.provider_type == provider_type)
-        .where(VoiceProvider.deleted.is_(False))
+        select(VoiceProvider).where(VoiceProvider.provider_type == provider_type)
     )
 
 
@@ -119,10 +108,10 @@ def upsert_voice_provider(
 
 
 def delete_voice_provider(db_session: Session, provider_id: int) -> None:
-    """Soft-delete a voice provider by ID."""
+    """Delete a voice provider by ID."""
     provider = fetch_voice_provider_by_id(db_session, provider_id)
     if provider:
-        provider.deleted = True
+        db_session.delete(provider)
         db_session.flush()
 
 

backend/onyx/llm/constants.py

@@ -25,6 +25,7 @@ class LlmProviderNames(str, Enum):
     LM_STUDIO = "lm_studio"
     MISTRAL = "mistral"
     LITELLM_PROXY = "litellm_proxy"
+    BIFROST = "bifrost"
 
     def __str__(self) -> str:
         """Needed so things like:
@@ -44,6 +45,7 @@ WELL_KNOWN_PROVIDER_NAMES = [
     LlmProviderNames.OLLAMA_CHAT,
     LlmProviderNames.LM_STUDIO,
     LlmProviderNames.LITELLM_PROXY,
+    LlmProviderNames.BIFROST,
 ]
 
 
@@ -61,6 +63,7 @@ PROVIDER_DISPLAY_NAMES: dict[str, str] = {
     LlmProviderNames.OLLAMA_CHAT: "Ollama",
     LlmProviderNames.LM_STUDIO: "LM Studio",
     LlmProviderNames.LITELLM_PROXY: "LiteLLM Proxy",
+    LlmProviderNames.BIFROST: "Bifrost",
     "groq": "Groq",
     "anyscale": "Anyscale",
     "deepseek": "DeepSeek",
@@ -112,6 +115,7 @@ AGGREGATOR_PROVIDERS: set[str] = {
     LlmProviderNames.VERTEX_AI,
     LlmProviderNames.AZURE,
     LlmProviderNames.LITELLM_PROXY,
+    LlmProviderNames.BIFROST,
 }
 
 # Model family name mappings for display name generation

backend/onyx/llm/multi_llm.py

@@ -290,6 +290,17 @@ class LitellmLLM(LLM):
         ):
             model_kwargs[VERTEX_LOCATION_KWARG] = "global"
 
+        # Bifrost: OpenAI-compatible proxy that expects model names in
+        # provider/model format (e.g. "anthropic/claude-sonnet-4-6").
+        # We route through LiteLLM's openai provider with the Bifrost base URL,
+        # and ensure /v1 is appended.
+        if model_provider == LlmProviderNames.BIFROST:
+            self._custom_llm_provider = "openai"
+            if self._api_base is not None:
+                base = self._api_base.rstrip("/")
+                self._api_base = base if base.endswith("/v1") else f"{base}/v1"
+                model_kwargs["api_base"] = self._api_base
+
         # This is needed for Ollama to do proper function calling
         if model_provider == LlmProviderNames.OLLAMA_CHAT and api_base is not None:
             model_kwargs["api_base"] = api_base
@@ -401,14 +412,20 @@ class LitellmLLM(LLM):
         optional_kwargs: dict[str, Any] = {}
 
         # Model name
+        is_bifrost = self._model_provider == LlmProviderNames.BIFROST
         model_provider = (
             f"{self.config.model_provider}/responses"
             if is_openai_model  # Uses litellm's completions -> responses bridge
             else self.config.model_provider
         )
-        model = (
-            f"{model_provider}/{self.config.deployment_name or self.config.model_name}"
-        )
+        if is_bifrost:
+            # Bifrost expects model names in provider/model format
+            # (e.g. "anthropic/claude-sonnet-4-6") sent directly to its
+            # OpenAI-compatible endpoint. We use custom_llm_provider="openai"
+            # so LiteLLM doesn't try to route based on the provider prefix.
+            model = self.config.deployment_name or self.config.model_name
+        else:
+            model = f"{model_provider}/{self.config.deployment_name or self.config.model_name}"
 
         # Tool choice
         if is_claude_model and tool_choice == ToolChoiceOptions.REQUIRED:
@@ -483,10 +500,11 @@ class LitellmLLM(LLM):
         if structured_response_format:
             optional_kwargs["response_format"] = structured_response_format
 
-        if not (is_claude_model or is_ollama or is_mistral):
+        if not (is_claude_model or is_ollama or is_mistral) or is_bifrost:
             # Litellm bug: tool_choice is dropped silently if not specified here for OpenAI
             # However, this param breaks Anthropic and Mistral models,
-            # so it must be conditionally included.
+            # so it must be conditionally included unless the request is
+            # routed through Bifrost's OpenAI-compatible endpoint.
             # Additionally, tool_choice is not supported by Ollama and causes warnings if included.
             # See also, https://github.com/ollama/ollama/issues/11171
             optional_kwargs["allowed_openai_params"] = ["tool_choice"]

backend/onyx/llm/well_known_providers/constants.py

@@ -13,6 +13,8 @@ LM_STUDIO_API_KEY_CONFIG_KEY = "LM_STUDIO_API_KEY"
 
 LITELLM_PROXY_PROVIDER_NAME = "litellm_proxy"
 
+BIFROST_PROVIDER_NAME = "bifrost"
+
 # Providers that use optional Bearer auth from custom_config
 PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING: dict[str, str] = {
     LlmProviderNames.OLLAMA_CHAT: OLLAMA_API_KEY_CONFIG_KEY,

backend/onyx/llm/well_known_providers/llm_provider_options.py

@@ -15,6 +15,7 @@ from onyx.llm.well_known_providers.auto_update_service import (
 from onyx.llm.well_known_providers.constants import ANTHROPIC_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import AZURE_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import BEDROCK_PROVIDER_NAME
+from onyx.llm.well_known_providers.constants import BIFROST_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import LITELLM_PROXY_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import LM_STUDIO_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OLLAMA_PROVIDER_NAME
@@ -49,6 +50,7 @@ def _get_provider_to_models_map() -> dict[str, list[str]]:
         LM_STUDIO_PROVIDER_NAME: [],  # Dynamic - fetched from LM Studio API
         OPENROUTER_PROVIDER_NAME: [],  # Dynamic - fetched from OpenRouter API
         LITELLM_PROXY_PROVIDER_NAME: [],  # Dynamic - fetched from LiteLLM proxy API
+        BIFROST_PROVIDER_NAME: [],  # Dynamic - fetched from Bifrost API
     }
 
 

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

@@ -44,11 +44,12 @@ def _check_ssrf_safety(endpoint_url: str) -> None:
     """Raise OnyxError if endpoint_url could be used for SSRF.
 
     Delegates to validate_outbound_http_url with https_only=True.
+    Uses BAD_GATEWAY so the frontend maps the error to the Endpoint URL field.
     """
     try:
         validate_outbound_http_url(endpoint_url, https_only=True)
     except (SSRFException, ValueError) as e:
-        raise OnyxError(OnyxErrorCode.INVALID_INPUT, str(e))
+        raise OnyxError(OnyxErrorCode.BAD_GATEWAY, str(e))
 
 
 # ---------------------------------------------------------------------------
@@ -141,19 +142,11 @@ def _validate_endpoint(
             )
         return HookValidateResponse(status=HookValidateStatus.passed)
     except httpx.TimeoutException as exc:
-        # ConnectTimeout: TCP handshake never completed → cannot_connect.
-        # ReadTimeout / WriteTimeout: TCP was established, server just responded slowly → timeout.
-        if isinstance(exc, httpx.ConnectTimeout):
-            logger.warning(
-                "Hook endpoint validation: connect timeout for %s",
-                endpoint_url,
-                exc_info=exc,
-            )
-            return HookValidateResponse(
-                status=HookValidateStatus.cannot_connect, error_message=str(exc)
-            )
+        # Any timeout (connect, read, or write) means the configured timeout_seconds
+        # is too low for this endpoint. Report as timeout so the UI directs the user
+        # to increase the timeout setting.
         logger.warning(
-            "Hook endpoint validation: read/write timeout for %s",
+            "Hook endpoint validation: timeout for %s",
             endpoint_url,
             exc_info=exc,
         )

backend/onyx/server/manage/llm/api.py

@@ -57,6 +57,8 @@ from onyx.llm.well_known_providers.llm_provider_options import (
 )
 from onyx.server.manage.llm.models import BedrockFinalModelResponse
 from onyx.server.manage.llm.models import BedrockModelsRequest
+from onyx.server.manage.llm.models import BifrostFinalModelResponse
+from onyx.server.manage.llm.models import BifrostModelsRequest
 from onyx.server.manage.llm.models import DefaultModel
 from onyx.server.manage.llm.models import LitellmFinalModelResponse
 from onyx.server.manage.llm.models import LitellmModelDetails
@@ -1422,11 +1424,26 @@ def _get_litellm_models_response(api_key: str, api_base: str) -> dict:
     cleaned_api_base = api_base.strip().rstrip("/")
     url = f"{cleaned_api_base}/v1/models"
 
+    return _get_openai_compatible_models_response(
+        url=url,
+        source_name="LiteLLM proxy",
+        api_key=api_key,
+    )
+
+
+def _get_openai_compatible_models_response(
+    url: str,
+    source_name: str,
+    api_key: str | None = None,
+) -> dict:
+    """Fetch model metadata from an OpenAI-compatible `/models` endpoint."""
     headers = {
         "Authorization": f"Bearer {api_key}",
         "HTTP-Referer": "https://onyx.app",
         "X-Title": "Onyx",
     }
+    if not api_key:
+        headers.pop("Authorization")
 
     try:
         response = httpx.get(url, headers=headers, timeout=10.0)
@@ -1436,20 +1453,125 @@ def _get_litellm_models_response(api_key: str, api_base: str) -> dict:
         if e.response.status_code == 401:
             raise OnyxError(
                 OnyxErrorCode.VALIDATION_ERROR,
-                "Authentication failed: invalid or missing API key for LiteLLM proxy.",
+                f"Authentication failed: invalid or missing API key for {source_name}.",
             )
         elif e.response.status_code == 404:
             raise OnyxError(
                 OnyxErrorCode.VALIDATION_ERROR,
-                f"LiteLLM models endpoint not found at {url}. Please verify the API base URL.",
+                f"{source_name} models endpoint not found at {url}. Please verify the API base URL.",
             )
         else:
             raise OnyxError(
                 OnyxErrorCode.BAD_GATEWAY,
-                f"Failed to fetch LiteLLM models: {e}",
+                f"Failed to fetch {source_name} models: {e}",
             )
-    except Exception as e:
+    except httpx.RequestError as e:
+        logger.warning(
+            "Failed to fetch models from OpenAI-compatible endpoint",
+            extra={"source": source_name, "url": url, "error": str(e)},
+            exc_info=True,
+        )
         raise OnyxError(
             OnyxErrorCode.BAD_GATEWAY,
-            f"Failed to fetch LiteLLM models: {e}",
+            f"Failed to fetch {source_name} models: {e}",
         )
+    except ValueError as e:
+        logger.warning(
+            "Received invalid model response from OpenAI-compatible endpoint",
+            extra={"source": source_name, "url": url, "error": str(e)},
+            exc_info=True,
+        )
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            f"Failed to fetch {source_name} models: {e}",
+        )
+
+
+@admin_router.post("/bifrost/available-models")
+def get_bifrost_available_models(
+    request: BifrostModelsRequest,
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> list[BifrostFinalModelResponse]:
+    """Fetch available models from Bifrost gateway /v1/models endpoint."""
+    response_json = _get_bifrost_models_response(
+        api_base=request.api_base, api_key=request.api_key
+    )
+
+    models = response_json.get("data", [])
+    if not isinstance(models, list) or len(models) == 0:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No models found from your Bifrost endpoint",
+        )
+
+    results: list[BifrostFinalModelResponse] = []
+    for model in models:
+        try:
+            model_id = model.get("id", "")
+            model_name = model.get("name", model_id)
+
+            if not model_id:
+                continue
+
+            # Skip embedding models
+            if is_embedding_model(model_id):
+                continue
+
+            results.append(
+                BifrostFinalModelResponse(
+                    name=model_id,
+                    display_name=model_name,
+                    max_input_tokens=model.get("context_length"),
+                    supports_image_input=infer_vision_support(model_id),
+                    supports_reasoning=is_reasoning_model(model_id, model_name),
+                )
+            )
+        except Exception as e:
+            logger.warning(
+                "Failed to parse Bifrost model entry",
+                extra={"error": str(e), "item": str(model)[:1000]},
+            )
+
+    if not results:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No compatible models found from Bifrost",
+        )
+
+    sorted_results = sorted(results, key=lambda m: m.name.lower())
+
+    # Sync new models to DB if provider_name is specified
+    if request.provider_name:
+        _sync_fetched_models(
+            db_session=db_session,
+            provider_name=request.provider_name,
+            models=[
+                SyncModelEntry(
+                    name=r.name,
+                    display_name=r.display_name,
+                    max_input_tokens=r.max_input_tokens,
+                    supports_image_input=r.supports_image_input,
+                )
+                for r in sorted_results
+            ],
+            source_label="Bifrost",
+        )
+
+    return sorted_results
+
+
+def _get_bifrost_models_response(api_base: str, api_key: str | None = None) -> dict:
+    """Perform GET to Bifrost /v1/models and return parsed JSON."""
+    cleaned_api_base = api_base.strip().rstrip("/")
+    # Ensure we hit /v1/models
+    if cleaned_api_base.endswith("/v1"):
+        url = f"{cleaned_api_base}/models"
+    else:
+        url = f"{cleaned_api_base}/v1/models"
+
+    return _get_openai_compatible_models_response(
+        url=url,
+        source_name="Bifrost",
+        api_key=api_key,
+    )

backend/onyx/server/manage/llm/models.py

@@ -449,3 +449,18 @@ class LitellmModelDetails(BaseModel):
 class LitellmFinalModelResponse(BaseModel):
     provider_name: str  # Provider name (e.g. "openai")
     model_name: str  # Model ID (e.g. "gpt-4o")
+
+
+# Bifrost dynamic models fetch
+class BifrostModelsRequest(BaseModel):
+    api_base: str
+    api_key: str | None = None
+    provider_name: str | None = None  # Optional: to save models to existing provider
+
+
+class BifrostFinalModelResponse(BaseModel):
+    name: str  # Model ID in provider/model format (e.g. "anthropic/claude-sonnet-4-6")
+    display_name: str  # Human-readable name from Bifrost API
+    max_input_tokens: int | None
+    supports_image_input: bool
+    supports_reasoning: bool

backend/onyx/server/manage/llm/utils.py

@@ -25,6 +25,7 @@ DYNAMIC_LLM_PROVIDERS = frozenset(
         LlmProviderNames.BEDROCK,
         LlmProviderNames.OLLAMA_CHAT,
         LlmProviderNames.LM_STUDIO,
+        LlmProviderNames.BIFROST,
     }
 )
 
@@ -50,6 +51,25 @@ BEDROCK_VISION_MODELS = frozenset(
     }
 )
 
+# Known Bifrost/OpenAI-compatible vision-capable model families where the
+# source API does not expose this metadata directly.
+BIFROST_VISION_MODEL_FAMILIES = frozenset(
+    {
+        "anthropic/claude-3",
+        "anthropic/claude-4",
+        "amazon/nova-pro",
+        "amazon/nova-lite",
+        "amazon/nova-premier",
+        "openai/gpt-4o",
+        "openai/gpt-4.1",
+        "google/gemini",
+        "meta-llama/llama-3.2",
+        "mistral/pixtral",
+        "qwen/qwen2.5-vl",
+        "qwen/qwen-vl",
+    }
+)
+
 
 def is_valid_bedrock_model(
     model_id: str,
@@ -76,11 +96,18 @@ def is_valid_bedrock_model(
 def infer_vision_support(model_id: str) -> bool:
     """Infer vision support from model ID when base model metadata unavailable.
 
-    Used for cross-region inference profiles when the base model isn't
-    available in the user's region.
+    Used for providers like Bedrock and Bifrost where vision support may
+    need to be inferred from vendor/model naming conventions.
     """
     model_id_lower = model_id.lower()
-    return any(vision_model in model_id_lower for vision_model in BEDROCK_VISION_MODELS)
+    if any(vision_model in model_id_lower for vision_model in BEDROCK_VISION_MODELS):
+        return True
+
+    normalized_model_id = model_id_lower.replace(".", "/")
+    return any(
+        vision_model in normalized_model_id
+        for vision_model in BIFROST_VISION_MODEL_FAMILIES
+    )
 
 
 def generate_bedrock_display_name(model_id: str) -> str:
@@ -322,7 +349,7 @@ def extract_vendor_from_model_name(model_name: str, provider: str) -> str | None
         - Ollama: "llama3:70b" → "Meta"
         - Ollama: "qwen2.5:7b" → "Alibaba"
     """
-    if provider == LlmProviderNames.OPENROUTER:
+    if provider in (LlmProviderNames.OPENROUTER, LlmProviderNames.BIFROST):
         # Format: "vendor/model-name" e.g., "anthropic/claude-3-5-sonnet"
         if "/" in model_name:
             vendor_key = model_name.split("/")[0].lower()

backend/onyx/server/metrics/indexing_pipeline.py

@@ -449,40 +449,128 @@ class RedisHealthCollector(_CachedCollector):
         return [memory_used, memory_peak, memory_frag, connected_clients]
 
 
-class WorkerHealthCollector(_CachedCollector):
-    """Collects Celery worker count and process count via inspect ping.
+class WorkerHeartbeatMonitor:
+    """Monitors Celery worker health via the event stream.
 
-    Uses a longer cache TTL (60s) since inspect.ping() is a broadcast
-    command that takes a couple seconds to complete.
-
-    Maintains a set of known worker short-names so that when a worker
-    stops responding, we emit ``up=0`` instead of silently dropping the
-    metric (which would make ``absent()``-style alerts impossible).
+    Subscribes to ``worker-heartbeat``, ``worker-online``, and
+    ``worker-offline`` events via a single persistent connection.
+    Runs in a daemon thread started once during worker setup.
     """
 
-    # Remove a worker from _known_workers after this many consecutive
-    # missed pings (at 60s TTL ≈ 10 minutes of being unreachable).
-    _MAX_CONSECUTIVE_MISSES = 10
+    # Consider a worker down if no heartbeat received for this long.
+    _HEARTBEAT_TIMEOUT_SECONDS = 120.0
 
-    def __init__(self, cache_ttl: float = 60.0) -> None:
+    def __init__(self, celery_app: Any) -> None:
+        self._app = celery_app
+        self._worker_last_seen: dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._running = False
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        """Start the background event listener thread.
+
+        Safe to call multiple times — only starts one thread.
+        """
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._running = True
+        self._thread = threading.Thread(target=self._listen, daemon=True)
+        self._thread.start()
+        logger.info("WorkerHeartbeatMonitor started")
+
+    def stop(self) -> None:
+        self._running = False
+
+    def _listen(self) -> None:
+        """Background loop: connect to event stream and process heartbeats."""
+        while self._running:
+            try:
+                with self._app.connection() as conn:
+                    recv = self._app.events.Receiver(
+                        conn,
+                        handlers={
+                            "worker-heartbeat": self._on_heartbeat,
+                            "worker-online": self._on_heartbeat,
+                            "worker-offline": self._on_offline,
+                        },
+                    )
+                    recv.capture(
+                        limit=None, timeout=self._HEARTBEAT_TIMEOUT_SECONDS, wakeup=True
+                    )
+            except Exception:
+                if self._running:
+                    logger.debug(
+                        "Heartbeat listener disconnected, reconnecting in 5s",
+                        exc_info=True,
+                    )
+                    time.sleep(5.0)
+            else:
+                # capture() returned normally (timeout with no events); reconnect
+                if self._running:
+                    logger.debug("Heartbeat capture timed out, reconnecting")
+                    time.sleep(5.0)
+
+    def _on_heartbeat(self, event: dict[str, Any]) -> None:
+        hostname = event.get("hostname")
+        if hostname:
+            with self._lock:
+                self._worker_last_seen[hostname] = time.monotonic()
+
+    def _on_offline(self, event: dict[str, Any]) -> None:
+        hostname = event.get("hostname")
+        if hostname:
+            with self._lock:
+                self._worker_last_seen.pop(hostname, None)
+
+    def get_worker_status(self) -> dict[str, bool]:
+        """Return {hostname: is_alive} for all known workers.
+
+        Thread-safe. Called by WorkerHealthCollector on each scrape.
+        Also prunes workers that have been dead longer than 2x the
+        heartbeat timeout to prevent unbounded growth.
+        """
+        now = time.monotonic()
+        prune_threshold = self._HEARTBEAT_TIMEOUT_SECONDS * 2
+        with self._lock:
+            # Prune workers that have been gone for 2x the timeout
+            stale = [
+                h
+                for h, ts in self._worker_last_seen.items()
+                if (now - ts) > prune_threshold
+            ]
+            for h in stale:
+                del self._worker_last_seen[h]
+
+            result: dict[str, bool] = {}
+            for hostname, last_seen in self._worker_last_seen.items():
+                alive = (now - last_seen) < self._HEARTBEAT_TIMEOUT_SECONDS
+                result[hostname] = alive
+            return result
+
+
+class WorkerHealthCollector(_CachedCollector):
+    """Collects Celery worker health from the heartbeat monitor.
+
+    Reads worker status from ``WorkerHeartbeatMonitor`` which listens
+    to the Celery event stream via a single persistent connection.
+    """
+
+    def __init__(self, cache_ttl: float = 30.0) -> None:
         super().__init__(cache_ttl)
-        self._celery_app: Any | None = None
-        # worker short-name → consecutive miss count.
-        # Workers start at 0 and reset to 0 each time they respond.
-        # Removed after _MAX_CONSECUTIVE_MISSES missed collects.
-        self._known_workers: dict[str, int] = {}
+        self._monitor: WorkerHeartbeatMonitor | None = None
 
-    def set_celery_app(self, app: Any) -> None:
-        """Set the Celery app instance for inspect commands."""
-        self._celery_app = app
+    def set_monitor(self, monitor: WorkerHeartbeatMonitor) -> None:
+        """Set the heartbeat monitor instance."""
+        self._monitor = monitor
 
     def _collect_fresh(self) -> list[GaugeMetricFamily]:
-        if self._celery_app is None:
+        if self._monitor is None:
             return []
 
         active_workers = GaugeMetricFamily(
             "onyx_celery_active_worker_count",
-            "Number of active Celery workers responding to ping",
+            "Number of active Celery workers with recent heartbeats",
         )
         worker_up = GaugeMetricFamily(
             "onyx_celery_worker_up",
@@ -491,37 +579,15 @@ class WorkerHealthCollector(_CachedCollector):
         )
 
         try:
-            inspector = self._celery_app.control.inspect(timeout=3.0)
-            ping_result = inspector.ping()
+            status = self._monitor.get_worker_status()
+            alive_count = sum(1 for alive in status.values() if alive)
+            active_workers.add_metric([], alive_count)
 
-            responding: set[str] = set()
-            if ping_result:
-                active_workers.add_metric([], len(ping_result))
-                for worker_name in ping_result:
-                    # Strip hostname suffix for cleaner labels
-                    short_name = worker_name.split("@")[0]
-                    responding.add(short_name)
-            else:
-                active_workers.add_metric([], 0)
-
-            # Register newly-seen workers and reset miss count for
-            # workers that responded.
-            for short_name in responding:
-                self._known_workers[short_name] = 0
-
-            # Increment miss count for non-responding workers and evict
-            # those that have been missing too long.
-            stale = []
-            for short_name in list(self._known_workers):
-                if short_name not in responding:
-                    self._known_workers[short_name] += 1
-                    if self._known_workers[short_name] >= self._MAX_CONSECUTIVE_MISSES:
-                        stale.append(short_name)
-            for short_name in stale:
-                del self._known_workers[short_name]
-
-            for short_name in sorted(self._known_workers):
-                worker_up.add_metric([short_name], 1 if short_name in responding else 0)
+            for hostname in sorted(status):
+                # Use short name (before @) for single-host deployments,
+                # full hostname when multiple hosts share a worker type.
+                label = hostname.split("@")[0]
+                worker_up.add_metric([label], 1 if status[hostname] else 0)
         except Exception:
             logger.debug("Failed to collect worker health metrics", exc_info=True)
 

backend/onyx/server/metrics/indexing_pipeline_setup.py

@@ -15,6 +15,7 @@ from onyx.server.metrics.indexing_pipeline import IndexAttemptCollector
 from onyx.server.metrics.indexing_pipeline import QueueDepthCollector
 from onyx.server.metrics.indexing_pipeline import RedisHealthCollector
 from onyx.server.metrics.indexing_pipeline import WorkerHealthCollector
+from onyx.server.metrics.indexing_pipeline import WorkerHeartbeatMonitor
 from onyx.utils.logger import setup_logger
 
 logger = setup_logger()
@@ -28,6 +29,7 @@ _attempt_collector = IndexAttemptCollector()
 _connector_collector = ConnectorHealthCollector()
 _redis_health_collector = RedisHealthCollector()
 _worker_health_collector = WorkerHealthCollector()
+_heartbeat_monitor: WorkerHeartbeatMonitor | None = None
 
 
 def _make_broker_redis_factory(celery_app: Celery) -> Callable[[], Redis]:
@@ -96,7 +98,16 @@ def setup_indexing_pipeline_metrics(celery_app: Celery) -> None:
     redis_factory = _make_broker_redis_factory(celery_app)
     _queue_collector.set_redis_factory(redis_factory)
     _redis_health_collector.set_redis_factory(redis_factory)
-    _worker_health_collector.set_celery_app(celery_app)
+
+    # Start the heartbeat monitor daemon thread — uses a single persistent
+    # connection to receive worker-heartbeat events.
+    # Module-level singleton prevents duplicate threads on re-entry.
+    global _heartbeat_monitor
+    if _heartbeat_monitor is None:
+        _heartbeat_monitor = WorkerHeartbeatMonitor(celery_app)
+        _heartbeat_monitor.start()
+    _worker_health_collector.set_monitor(_heartbeat_monitor)
+
     _attempt_collector.configure()
     _connector_collector.configure()
 

backend/tests/external_dependency_unit/connectors/confluence/test_confluence_group_sync.py

@@ -103,6 +103,11 @@ _EXPECTED_CONFLUENCE_GROUPS = [
         user_emails={"oauth@onyx.app"},
         gives_anyone_access=False,
     ),
+    ExternalUserGroupSet(
+        id="no yuhong allowed",
+        user_emails={"hagen@danswer.ai", "pablo@onyx.app", "chris@onyx.app"},
+        gives_anyone_access=False,
+    ),
 ]
 
 

backend/tests/unit/onyx/connectors/canvas/test_canvas_connector.py

@@ -0,0 +1,381 @@
+"""Tests for Canvas connector — client (PR1)."""
+
+from typing import Any
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import pytest
+
+from onyx.connectors.canvas.client import CanvasApiClient
+from onyx.error_handling.exceptions import OnyxError
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+FAKE_BASE_URL = "https://myschool.instructure.com"
+FAKE_TOKEN = "fake-canvas-token"
+
+
+def _mock_response(
+    status_code: int = 200,
+    json_data: Any = None,
+    link_header: str = "",
+) -> MagicMock:
+    """Create a mock HTTP response with status, json, and Link header."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.reason = "OK" if status_code < 300 else "Error"
+    resp.json.return_value = json_data if json_data is not None else []
+    resp.headers = {"Link": link_header}
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# CanvasApiClient.__init__ tests
+# ---------------------------------------------------------------------------
+
+
+class TestCanvasApiClientInit:
+    def test_success(self) -> None:
+        client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=FAKE_BASE_URL,
+        )
+
+        expected_base_url = f"{FAKE_BASE_URL}/api/v1"
+        expected_host = "myschool.instructure.com"
+
+        assert client.base_url == expected_base_url
+        assert client._expected_host == expected_host
+
+    def test_normalizes_trailing_slash(self) -> None:
+        client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=f"{FAKE_BASE_URL}/",
+        )
+
+        expected_base_url = f"{FAKE_BASE_URL}/api/v1"
+
+        assert client.base_url == expected_base_url
+
+    def test_normalizes_existing_api_v1(self) -> None:
+        client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=f"{FAKE_BASE_URL}/api/v1",
+        )
+
+        expected_base_url = f"{FAKE_BASE_URL}/api/v1"
+
+        assert client.base_url == expected_base_url
+
+    def test_rejects_non_https_scheme(self) -> None:
+        with pytest.raises(ValueError, match="must use https"):
+            CanvasApiClient(
+                bearer_token=FAKE_TOKEN,
+                canvas_base_url="ftp://myschool.instructure.com",
+            )
+
+    def test_rejects_http(self) -> None:
+        with pytest.raises(ValueError, match="must use https"):
+            CanvasApiClient(
+                bearer_token=FAKE_TOKEN,
+                canvas_base_url="http://myschool.instructure.com",
+            )
+
+    def test_rejects_missing_host(self) -> None:
+        with pytest.raises(ValueError, match="must include a valid host"):
+            CanvasApiClient(
+                bearer_token=FAKE_TOKEN,
+                canvas_base_url="https://",
+            )
+
+
+# ---------------------------------------------------------------------------
+# CanvasApiClient._build_url tests
+# ---------------------------------------------------------------------------
+
+
+class TestBuildUrl:
+    def setup_method(self) -> None:
+        self.client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=FAKE_BASE_URL,
+        )
+
+    def test_appends_endpoint(self) -> None:
+        result = self.client._build_url("courses")
+        expected = f"{FAKE_BASE_URL}/api/v1/courses"
+
+        assert result == expected
+
+    def test_strips_leading_slash_from_endpoint(self) -> None:
+        result = self.client._build_url("/courses")
+        expected = f"{FAKE_BASE_URL}/api/v1/courses"
+
+        assert result == expected
+
+
+# ---------------------------------------------------------------------------
+# CanvasApiClient._build_headers tests
+# ---------------------------------------------------------------------------
+
+
+class TestBuildHeaders:
+    def setup_method(self) -> None:
+        self.client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=FAKE_BASE_URL,
+        )
+
+    def test_returns_bearer_auth(self) -> None:
+        result = self.client._build_headers()
+        expected = {"Authorization": f"Bearer {FAKE_TOKEN}"}
+
+        assert result == expected
+
+
+# ---------------------------------------------------------------------------
+# CanvasApiClient.get tests
+# ---------------------------------------------------------------------------
+
+
+class TestGet:
+    def setup_method(self) -> None:
+        self.client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url=FAKE_BASE_URL,
+        )
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_success_returns_json_and_next_url(self, mock_requests: MagicMock) -> None:
+        next_link = f"<{FAKE_BASE_URL}/api/v1/courses?page=2>; " 'rel="next"'
+        mock_requests.get.return_value = _mock_response(
+            json_data=[{"id": 1}], link_header=next_link
+        )
+
+        data, next_url = self.client.get("courses")
+
+        expected_data = [{"id": 1}]
+        expected_next = f"{FAKE_BASE_URL}/api/v1/courses?page=2"
+
+        assert data == expected_data
+        assert next_url == expected_next
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_success_no_next_page(self, mock_requests: MagicMock) -> None:
+        mock_requests.get.return_value = _mock_response(json_data=[{"id": 1}])
+
+        data, next_url = self.client.get("courses")
+
+        assert data == [{"id": 1}]
+        assert next_url is None
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_raises_on_error_status(self, mock_requests: MagicMock) -> None:
+        mock_requests.get.return_value = _mock_response(403, {})
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        assert exc_info.value.status_code == 403
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_raises_on_404(self, mock_requests: MagicMock) -> None:
+        mock_requests.get.return_value = _mock_response(404, {})
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        assert exc_info.value.status_code == 404
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_raises_on_429(self, mock_requests: MagicMock) -> None:
+        mock_requests.get.return_value = _mock_response(429, {})
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        assert exc_info.value.status_code == 429
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_skips_params_when_using_full_url(self, mock_requests: MagicMock) -> None:
+        mock_requests.get.return_value = _mock_response(json_data=[])
+        full = f"{FAKE_BASE_URL}/api/v1/courses?page=2"
+
+        self.client.get(params={"per_page": "100"}, full_url=full)
+
+        _, kwargs = mock_requests.get.call_args
+        assert kwargs["params"] is None
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_error_extracts_message_from_error_dict(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """Shape 1: {"error": {"message": "Not authorized"}}"""
+        mock_requests.get.return_value = _mock_response(
+            403, {"error": {"message": "Not authorized"}}
+        )
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Not authorized"
+
+        assert result == expected
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_error_extracts_message_from_error_string(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """Shape 2: {"error": "Invalid access token"}"""
+        mock_requests.get.return_value = _mock_response(
+            401, {"error": "Invalid access token"}
+        )
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Invalid access token"
+
+        assert result == expected
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_error_extracts_message_from_errors_list(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """Shape 3: {"errors": [{"message": "Invalid query"}]}"""
+        mock_requests.get.return_value = _mock_response(
+            400, {"errors": [{"message": "Invalid query"}]}
+        )
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Invalid query"
+
+        assert result == expected
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_error_dict_takes_priority_over_errors_list(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """When both error shapes are present, error dict wins."""
+        mock_requests.get.return_value = _mock_response(
+            403, {"error": "Specific error", "errors": [{"message": "Generic"}]}
+        )
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Specific error"
+
+        assert result == expected
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_error_falls_back_to_reason_when_no_json_message(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """Empty error body falls back to response.reason."""
+        mock_requests.get.return_value = _mock_response(500, {})
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Error"  # from _mock_response's reason for >= 300
+
+        assert result == expected
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_invalid_json_on_success_raises(self, mock_requests: MagicMock) -> None:
+        """Invalid JSON on a 2xx response raises OnyxError."""
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.json.side_effect = ValueError("No JSON")
+        resp.headers = {"Link": ""}
+        mock_requests.get.return_value = resp
+
+        with pytest.raises(OnyxError, match="Invalid JSON"):
+            self.client.get("courses")
+
+    @patch("onyx.connectors.canvas.client.rl_requests")
+    def test_invalid_json_on_error_falls_back_to_reason(
+        self, mock_requests: MagicMock
+    ) -> None:
+        """Invalid JSON on a 4xx response falls back to response.reason."""
+        resp = MagicMock()
+        resp.status_code = 500
+        resp.reason = "Internal Server Error"
+        resp.json.side_effect = ValueError("No JSON")
+        resp.headers = {"Link": ""}
+        mock_requests.get.return_value = resp
+
+        with pytest.raises(OnyxError) as exc_info:
+            self.client.get("courses")
+
+        result = exc_info.value.detail
+        expected = "Internal Server Error"
+
+        assert result == expected
+
+
+# ---------------------------------------------------------------------------
+# CanvasApiClient._parse_next_link tests
+# ---------------------------------------------------------------------------
+
+
+class TestParseNextLink:
+    def setup_method(self) -> None:
+        self.client = CanvasApiClient(
+            bearer_token=FAKE_TOKEN,
+            canvas_base_url="https://canvas.example.com",
+        )
+
+    def test_found(self) -> None:
+        header = '<https://canvas.example.com/api/v1/courses?page=2>; rel="next"'
+
+        result = self.client._parse_next_link(header)
+        expected = "https://canvas.example.com/api/v1/courses?page=2"
+
+        assert result == expected
+
+    def test_not_found(self) -> None:
+        header = '<https://canvas.example.com/api/v1/courses?page=1>; rel="current"'
+
+        result = self.client._parse_next_link(header)
+
+        assert result is None
+
+    def test_empty(self) -> None:
+        result = self.client._parse_next_link("")
+
+        assert result is None
+
+    def test_multiple_rels(self) -> None:
+        header = (
+            '<https://canvas.example.com/api/v1/courses?page=1>; rel="current", '
+            '<https://canvas.example.com/api/v1/courses?page=2>; rel="next"'
+        )
+
+        result = self.client._parse_next_link(header)
+        expected = "https://canvas.example.com/api/v1/courses?page=2"
+
+        assert result == expected
+
+    def test_rejects_host_mismatch(self) -> None:
+        header = '<https://evil.example.com/api/v1/courses?page=2>; rel="next"'
+
+        with pytest.raises(OnyxError, match="unexpected host"):
+            self.client._parse_next_link(header)
+
+    def test_rejects_non_https_link(self) -> None:
+        header = '<http://canvas.example.com/api/v1/courses?page=2>; rel="next"'
+
+        with pytest.raises(OnyxError, match="must use https"):
+            self.client._parse_next_link(header)

backend/tests/unit/onyx/connectors/jira/test_jira_bulk_fetch.py

@@ -0,0 +1,147 @@
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+from jira import JIRA
+from jira.resources import Issue
+
+from onyx.connectors.jira.connector import bulk_fetch_issues
+
+
+def _make_raw_issue(issue_id: str) -> dict[str, Any]:
+    return {
+        "id": issue_id,
+        "key": f"TEST-{issue_id}",
+        "fields": {"summary": f"Issue {issue_id}"},
+    }
+
+
+def _mock_jira_client() -> MagicMock:
+    mock = MagicMock(spec=JIRA)
+    mock._options = {"server": "https://jira.example.com"}
+    mock._session = MagicMock()
+    mock._get_url = MagicMock(
+        return_value="https://jira.example.com/rest/api/3/issue/bulkfetch"
+    )
+    return mock
+
+
+def test_bulk_fetch_success() -> None:
+    """Happy path: all issues fetched in one request."""
+    client = _mock_jira_client()
+    raw = [_make_raw_issue("1"), _make_raw_issue("2"), _make_raw_issue("3")]
+    resp = MagicMock()
+    resp.json.return_value = {"issues": raw}
+    client._session.post.return_value = resp
+
+    result = bulk_fetch_issues(client, ["1", "2", "3"])
+    assert len(result) == 3
+    assert all(isinstance(r, Issue) for r in result)
+    client._session.post.assert_called_once()
+
+
+def test_bulk_fetch_splits_on_json_error() -> None:
+    """When the full batch fails with JSONDecodeError, sub-batches succeed."""
+    client = _mock_jira_client()
+
+    call_count = 0
+
+    def _post_side_effect(url: str, json: dict[str, Any]) -> MagicMock:  # noqa: ARG001
+        nonlocal call_count
+        call_count += 1
+        ids = json["issueIdsOrKeys"]
+        if len(ids) > 2:
+            resp = MagicMock()
+            resp.json.side_effect = requests.exceptions.JSONDecodeError(
+                "Expecting ',' delimiter", "doc", 2294125
+            )
+            return resp
+
+        resp = MagicMock()
+        resp.json.return_value = {"issues": [_make_raw_issue(i) for i in ids]}
+        return resp
+
+    client._session.post.side_effect = _post_side_effect
+
+    result = bulk_fetch_issues(client, ["1", "2", "3", "4"])
+    assert len(result) == 4
+    returned_ids = {r.raw["id"] for r in result}
+    assert returned_ids == {"1", "2", "3", "4"}
+    assert call_count > 1
+
+
+def test_bulk_fetch_raises_on_single_unfetchable_issue() -> None:
+    """A single issue that always fails JSON decode raises after splitting."""
+    client = _mock_jira_client()
+
+    def _post_side_effect(url: str, json: dict[str, Any]) -> MagicMock:  # noqa: ARG001
+        ids = json["issueIdsOrKeys"]
+        if "bad" in ids:
+            resp = MagicMock()
+            resp.json.side_effect = requests.exceptions.JSONDecodeError(
+                "Expecting ',' delimiter", "doc", 100
+            )
+            return resp
+
+        resp = MagicMock()
+        resp.json.return_value = {"issues": [_make_raw_issue(i) for i in ids]}
+        return resp
+
+    client._session.post.side_effect = _post_side_effect
+
+    with pytest.raises(requests.exceptions.JSONDecodeError):
+        bulk_fetch_issues(client, ["1", "bad", "2"])
+
+
+def test_bulk_fetch_non_json_error_propagates() -> None:
+    """Non-JSONDecodeError exceptions still propagate."""
+    client = _mock_jira_client()
+
+    resp = MagicMock()
+    resp.json.side_effect = ValueError("something else broke")
+    client._session.post.return_value = resp
+
+    try:
+        bulk_fetch_issues(client, ["1"])
+        assert False, "Expected ValueError to propagate"
+    except ValueError:
+        pass
+
+
+def test_bulk_fetch_with_fields() -> None:
+    """Fields parameter is forwarded correctly."""
+    client = _mock_jira_client()
+    raw = [_make_raw_issue("1")]
+    resp = MagicMock()
+    resp.json.return_value = {"issues": raw}
+    client._session.post.return_value = resp
+
+    bulk_fetch_issues(client, ["1"], fields="summary,description")
+
+    call_payload = client._session.post.call_args[1]["json"]
+    assert call_payload["fields"] == ["summary", "description"]
+
+
+def test_bulk_fetch_recursive_splitting_raises_on_bad_issue() -> None:
+    """With a 6-issue batch where one is bad, recursion isolates it and raises."""
+    client = _mock_jira_client()
+    bad_id = "BAD"
+
+    def _post_side_effect(url: str, json: dict[str, Any]) -> MagicMock:  # noqa: ARG001
+        ids = json["issueIdsOrKeys"]
+        if bad_id in ids:
+            resp = MagicMock()
+            resp.json.side_effect = requests.exceptions.JSONDecodeError(
+                "truncated", "doc", 999
+            )
+            return resp
+
+        resp = MagicMock()
+        resp.json.return_value = {"issues": [_make_raw_issue(i) for i in ids]}
+        return resp
+
+    client._session.post.side_effect = _post_side_effect
+
+    with pytest.raises(requests.exceptions.JSONDecodeError):
+        bulk_fetch_issues(client, ["1", "2", bad_id, "3", "4", "5"])

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

@@ -272,13 +272,13 @@ class TestUpsertVoiceProvider:
 class TestDeleteVoiceProvider:
     """Tests for delete_voice_provider."""
 
-    def test_soft_deletes_provider_when_found(self, mock_db_session: MagicMock) -> None:
+    def test_hard_deletes_provider_when_found(self, mock_db_session: MagicMock) -> None:
         provider = _make_voice_provider(id=1)
         mock_db_session.scalar.return_value = provider
 
         delete_voice_provider(mock_db_session, 1)
 
-        assert provider.deleted is True
+        mock_db_session.delete.assert_called_once_with(provider)
         mock_db_session.flush.assert_called_once()
 
     def test_does_nothing_when_provider_not_found(

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

@@ -1462,3 +1462,69 @@ def test_no_tool_choice_sent_when_no_tools(default_multi_llm: LitellmLLM) -> Non
         assert (
             "tool_choice" not in kwargs
         ), "tool_choice must not be sent to providers when no tools are provided"
+
+
+def test_bifrost_normalizes_api_base_in_model_kwargs() -> None:
+    llm = LitellmLLM(
+        api_key="test_key",
+        api_base="https://bifrost.example.com/",
+        timeout=30,
+        model_provider=LlmProviderNames.BIFROST,
+        model_name="anthropic/claude-sonnet-4-6",
+        max_input_tokens=32000,
+    )
+
+    assert llm._custom_llm_provider == "openai"
+    assert llm._api_base == "https://bifrost.example.com/v1"
+    assert llm._model_kwargs["api_base"] == "https://bifrost.example.com/v1"
+
+
+def test_bifrost_claude_includes_allowed_openai_params() -> None:
+    llm = LitellmLLM(
+        api_key="test_key",
+        api_base="https://bifrost.example.com",
+        timeout=30,
+        model_provider=LlmProviderNames.BIFROST,
+        model_name="anthropic/claude-sonnet-4-6",
+        max_input_tokens=32000,
+    )
+
+    messages: LanguageModelInput = [UserMessage(content="Use a tool if needed")]
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "lookup",
+                "description": "Look up data",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}},
+                    "required": ["query"],
+                },
+            },
+        }
+    ]
+    mock_stream_chunks = [
+        litellm.ModelResponse(
+            id="chatcmpl-123",
+            choices=[
+                litellm.Choices(
+                    delta=_create_delta(role="assistant", content="Done"),
+                    finish_reason="stop",
+                    index=0,
+                )
+            ],
+            model="anthropic/claude-sonnet-4-6",
+        ),
+    ]
+
+    with patch("litellm.completion") as mock_completion:
+        mock_completion.return_value = mock_stream_chunks
+
+        llm.invoke(messages, tools=tools)
+
+        kwargs = mock_completion.call_args.kwargs
+        assert kwargs["model"] == "anthropic/claude-sonnet-4-6"
+        assert kwargs["base_url"] == "https://bifrost.example.com/v1"
+        assert kwargs["custom_llm_provider"] == "openai"
+        assert kwargs["allowed_openai_params"] == ["tool_choice"]

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

@@ -3,7 +3,7 @@
 Covers:
 - _check_ssrf_safety: scheme enforcement and private-IP blocklist
 - _validate_endpoint: httpx exception → HookValidateStatus mapping
-  ConnectTimeout     → cannot_connect  (TCP handshake never completed)
+  ConnectTimeout     → timeout         (any timeout directs user to increase timeout_seconds)
   ConnectError       → cannot_connect  (DNS / TLS failure)
   ReadTimeout et al. → timeout         (TCP connected, server slow)
   Any other exc      → cannot_connect
@@ -61,7 +61,7 @@ class TestCheckSsrfSafety:
     def test_non_https_scheme_rejected(self, url: str) -> None:
         with pytest.raises(OnyxError) as exc_info:
             self._call(url)
-        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+        assert exc_info.value.error_code == OnyxErrorCode.BAD_GATEWAY
         assert "https" in (exc_info.value.detail or "").lower()
 
     # --- private IP blocklist ---
@@ -87,7 +87,7 @@ class TestCheckSsrfSafety:
         ):
             mock_dns.return_value = [(None, None, None, None, (ip, 0))]
             self._call("https://internal.example.com/hook")
-        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+        assert exc_info.value.error_code == OnyxErrorCode.BAD_GATEWAY
         assert ip in (exc_info.value.detail or "")
 
     def test_public_ip_is_allowed(self) -> None:
@@ -106,7 +106,7 @@ class TestCheckSsrfSafety:
             pytest.raises(OnyxError) as exc_info,
         ):
             self._call("https://no-such-host.example.com/hook")
-        assert exc_info.value.error_code == OnyxErrorCode.INVALID_INPUT
+        assert exc_info.value.error_code == OnyxErrorCode.BAD_GATEWAY
 
 
 # ---------------------------------------------------------------------------
@@ -158,13 +158,11 @@ class TestValidateEndpoint:
         assert self._call().status == HookValidateStatus.passed
 
     @patch("onyx.server.features.hooks.api.httpx.Client")
-    def test_connect_timeout_returns_cannot_connect(
-        self, mock_client_cls: MagicMock
-    ) -> None:
+    def test_connect_timeout_returns_timeout(self, mock_client_cls: MagicMock) -> None:
         mock_client_cls.return_value.__enter__.return_value.post.side_effect = (
             httpx.ConnectTimeout("timed out")
         )
-        assert self._call().status == HookValidateStatus.cannot_connect
+        assert self._call().status == HookValidateStatus.timeout
 
     @patch("onyx.server.features.hooks.api.httpx.Client")
     @pytest.mark.parametrize(

backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py

@@ -12,6 +12,8 @@ import httpx
 import pytest
 
 from onyx.error_handling.exceptions import OnyxError
+from onyx.server.manage.llm.models import BifrostFinalModelResponse
+from onyx.server.manage.llm.models import BifrostModelsRequest
 from onyx.server.manage.llm.models import LitellmFinalModelResponse
 from onyx.server.manage.llm.models import LitellmModelsRequest
 from onyx.server.manage.llm.models import LMStudioFinalModelResponse
@@ -850,13 +852,15 @@ class TestGetLitellmAvailableModels:
         mock_session = MagicMock()
 
         with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
-            mock_get.side_effect = Exception("Connection refused")
+            mock_get.side_effect = httpx.ConnectError(
+                "Connection refused", request=MagicMock()
+            )
 
             request = LitellmModelsRequest(
                 api_base="http://localhost:4000",
                 api_key="test-key",
             )
-            with pytest.raises(OnyxError, match="Failed to fetch LiteLLM models"):
+            with pytest.raises(OnyxError, match="Failed to fetch LiteLLM proxy models"):
                 get_litellm_available_models(request, MagicMock(), mock_session)
 
     def test_401_raises_authentication_error(self) -> None:
@@ -898,3 +902,113 @@ class TestGetLitellmAvailableModels:
             )
             with pytest.raises(OnyxError, match="endpoint not found"):
                 get_litellm_available_models(request, MagicMock(), mock_session)
+
+
+class TestGetBifrostAvailableModels:
+    """Tests for the Bifrost model fetch endpoint."""
+
+    @pytest.fixture
+    def mock_bifrost_response(self) -> dict:
+        """Mock response from Bifrost /v1/models endpoint."""
+        return {
+            "data": [
+                {
+                    "id": "anthropic/claude-3-5-sonnet",
+                    "name": "Claude 3.5 Sonnet",
+                    "context_length": 200000,
+                },
+                {
+                    "id": "openai/gpt-4o",
+                    "name": "GPT-4o",
+                    "context_length": 128000,
+                },
+                {
+                    "id": "deepseek/deepseek-r1",
+                    "name": "DeepSeek R1",
+                    "context_length": 64000,
+                },
+            ]
+        }
+
+    def test_returns_model_list(self, mock_bifrost_response: dict) -> None:
+        """Test that endpoint returns properly formatted non-embedding models."""
+        from onyx.server.manage.llm.api import get_bifrost_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_bifrost_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = BifrostModelsRequest(api_base="https://bifrost.example.com")
+            results = get_bifrost_available_models(request, MagicMock(), mock_session)
+
+            assert len(results) == 3
+            assert all(isinstance(r, BifrostFinalModelResponse) for r in results)
+            assert [r.name for r in results] == sorted(
+                [r.name for r in results], key=str.lower
+            )
+
+    def test_infers_vision_support(self, mock_bifrost_response: dict) -> None:
+        """Test that vision support is inferred from provider/model IDs."""
+        from onyx.server.manage.llm.api import get_bifrost_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_bifrost_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = BifrostModelsRequest(api_base="https://bifrost.example.com")
+            results = get_bifrost_available_models(request, MagicMock(), mock_session)
+
+            claude = next(r for r in results if r.name == "anthropic/claude-3-5-sonnet")
+            gpt4o = next(r for r in results if r.name == "openai/gpt-4o")
+            deepseek = next(r for r in results if r.name == "deepseek/deepseek-r1")
+
+            assert claude.supports_image_input is True
+            assert gpt4o.supports_image_input is True
+            assert deepseek.supports_image_input is False
+
+    def test_existing_v1_suffix_is_not_duplicated(self) -> None:
+        """Test that an existing /v1 suffix still hits a single /v1/models endpoint."""
+        from onyx.server.manage.llm.api import get_bifrost_available_models
+
+        mock_session = MagicMock()
+        response = {"data": [{"id": "openai/gpt-4o", "name": "GPT-4o"}]}
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = BifrostModelsRequest(api_base="https://bifrost.example.com/v1")
+            get_bifrost_available_models(request, MagicMock(), mock_session)
+
+            called_url = mock_get.call_args[0][0]
+            assert called_url == "https://bifrost.example.com/v1/models"
+
+    def test_request_failure_is_logged_and_wrapped(self) -> None:
+        """Test that request-layer failures are logged before raising OnyxError."""
+        from onyx.server.manage.llm.api import get_bifrost_available_models
+
+        mock_session = MagicMock()
+
+        with (
+            patch("onyx.server.manage.llm.api.httpx.get") as mock_get,
+            patch("onyx.server.manage.llm.api.logger.warning") as mock_warning,
+        ):
+            mock_get.side_effect = httpx.ConnectError(
+                "Connection refused", request=MagicMock()
+            )
+
+            request = BifrostModelsRequest(api_base="https://bifrost.example.com")
+            with pytest.raises(OnyxError, match="Failed to fetch Bifrost models"):
+                get_bifrost_available_models(request, MagicMock(), mock_session)
+
+            mock_warning.assert_called_once()

backend/tests/unit/onyx/server/manage/llm/test_llm_provider_utils.py

@@ -176,6 +176,14 @@ class TestInferVisionSupport:
         """Test Nova Pro has vision."""
         assert infer_vision_support("amazon.nova-pro-v1") is True
 
+    def test_bifrost_claude_has_vision(self) -> None:
+        """Test Bifrost Claude models are recognized as vision-capable."""
+        assert infer_vision_support("anthropic/claude-3-5-sonnet") is True
+
+    def test_bifrost_gpt4o_has_vision(self) -> None:
+        """Test Bifrost GPT-4o models are recognized as vision-capable."""
+        assert infer_vision_support("openai/gpt-4o") is True
+
     def test_mistral_no_vision(self) -> None:
         """Test Mistral doesn't have vision (not in known list)."""
         assert infer_vision_support("mistral.mistral-large") is False

backend/tests/unit/server/metrics/test_worker_health.py

@@ -0,0 +1,170 @@
+"""Tests for WorkerHeartbeatMonitor and WorkerHealthCollector."""
+
+import time
+from unittest.mock import MagicMock
+
+from onyx.server.metrics.indexing_pipeline import WorkerHealthCollector
+from onyx.server.metrics.indexing_pipeline import WorkerHeartbeatMonitor
+
+
+class TestWorkerHeartbeatMonitor:
+    def test_heartbeat_registers_worker(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+
+        status = monitor.get_worker_status()
+        assert "primary@host1" in status
+        assert status["primary@host1"] is True
+
+    def test_multiple_workers(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        monitor._on_heartbeat({"hostname": "docfetching@host1"})
+        monitor._on_heartbeat({"hostname": "monitoring@host1"})
+
+        status = monitor.get_worker_status()
+        assert len(status) == 3
+        assert all(alive for alive in status.values())
+
+    def test_offline_removes_worker(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        monitor._on_offline({"hostname": "primary@host1"})
+
+        status = monitor.get_worker_status()
+        assert "primary@host1" not in status
+
+    def test_stale_heartbeat_marks_worker_down(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        with monitor._lock:
+            monitor._worker_last_seen["primary@host1"] = (
+                time.monotonic() - monitor._HEARTBEAT_TIMEOUT_SECONDS - 10
+            )
+
+        status = monitor.get_worker_status()
+        assert status["primary@host1"] is False
+
+    def test_very_stale_worker_is_pruned(self) -> None:
+        """Workers dead for 2x the timeout are pruned from the dict."""
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        with monitor._lock:
+            monitor._worker_last_seen["gone@host1"] = (
+                time.monotonic() - monitor._HEARTBEAT_TIMEOUT_SECONDS * 2 - 10
+            )
+
+        status = monitor.get_worker_status()
+        assert "gone@host1" not in status
+        assert monitor.get_worker_status() == {}
+
+    def test_heartbeat_refreshes_stale_worker(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        with monitor._lock:
+            monitor._worker_last_seen["primary@host1"] = (
+                time.monotonic() - monitor._HEARTBEAT_TIMEOUT_SECONDS - 10
+            )
+        assert monitor.get_worker_status()["primary@host1"] is False
+
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        assert monitor.get_worker_status()["primary@host1"] is True
+
+    def test_ignores_empty_hostname(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({})
+        monitor._on_heartbeat({"hostname": ""})
+        monitor._on_offline({})
+
+        assert monitor.get_worker_status() == {}
+
+    def test_returns_full_hostname_as_key(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "docprocessing@my-long-host.local"})
+
+        status = monitor.get_worker_status()
+        assert "docprocessing@my-long-host.local" in status
+
+    def test_start_is_idempotent(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        # Mock the thread so we don't actually start one
+        mock_thread = MagicMock()
+        mock_thread.is_alive.return_value = True
+        monitor._thread = mock_thread
+        monitor._running = True
+
+        # Second start should be a no-op
+        monitor.start()
+        # Thread constructor should not have been called again
+        assert monitor._thread is mock_thread
+
+    def test_thread_safety(self) -> None:
+        """get_worker_status should not raise even if heartbeats arrive concurrently."""
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        status = monitor.get_worker_status()
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        status2 = monitor.get_worker_status()
+        assert status == status2
+
+
+class TestWorkerHealthCollector:
+    def test_returns_empty_when_no_monitor(self) -> None:
+        collector = WorkerHealthCollector(cache_ttl=0)
+        assert collector.collect() == []
+
+    def test_collects_active_workers(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        monitor._on_heartbeat({"hostname": "docfetching@host1"})
+        monitor._on_heartbeat({"hostname": "monitoring@host1"})
+
+        collector = WorkerHealthCollector(cache_ttl=0)
+        collector.set_monitor(monitor)
+
+        families = collector.collect()
+        assert len(families) == 2
+
+        active = families[0]
+        assert active.name == "onyx_celery_active_worker_count"
+        assert active.samples[0].value == 3
+
+        up = families[1]
+        assert up.name == "onyx_celery_worker_up"
+        assert len(up.samples) == 3
+        # Labels use short names (before @)
+        labels = {s.labels["worker"] for s in up.samples}
+        assert labels == {"primary", "docfetching", "monitoring"}
+        for sample in up.samples:
+            assert sample.value == 1
+
+    def test_reports_dead_worker(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+        monitor._on_heartbeat({"hostname": "primary@host1"})
+        with monitor._lock:
+            monitor._worker_last_seen["monitoring@host1"] = (
+                time.monotonic() - monitor._HEARTBEAT_TIMEOUT_SECONDS - 10
+            )
+
+        collector = WorkerHealthCollector(cache_ttl=0)
+        collector.set_monitor(monitor)
+
+        families = collector.collect()
+        active = families[0]
+        assert active.samples[0].value == 1
+
+        up = families[1]
+        samples_by_name = {s.labels["worker"]: s.value for s in up.samples}
+        assert samples_by_name["primary"] == 1
+        assert samples_by_name["monitoring"] == 0
+
+    def test_empty_monitor_returns_zero(self) -> None:
+        monitor = WorkerHeartbeatMonitor(MagicMock())
+
+        collector = WorkerHealthCollector(cache_ttl=0)
+        collector.set_monitor(monitor)
+
+        families = collector.collect()
+        assert len(families) == 2
+        active = families[0]
+        assert active.samples[0].value == 0
+        up = families[1]
+        assert up.name == "onyx_celery_worker_up"
+        assert len(up.samples) == 0

greptile.json

@@ -1,128 +0,0 @@
-{
-    "labels": [],
-    "comment": "",
-    "fixWithAI": true,
-    "hideFooter": false,
-    "strictness": 2,
-    "statusCheck": true,
-    "commentTypes": [
-      "logic",
-      "syntax",
-      "style"
-    ],
-    "instructions": "",
-    "disabledLabels": [],
-    "excludeAuthors": [
-      "dependabot[bot]",
-      "renovate[bot]"
-    ],
-    "ignoreKeywords": "",
-    "ignorePatterns": "greptile.json\n",
-    "includeAuthors": [],
-    "summarySection": {
-      "included": true,
-      "collapsible": false,
-      "defaultOpen": false
-    },
-    "excludeBranches": [],
-    "fileChangeLimit": 300,
-    "includeBranches": [],
-    "includeKeywords": "",
-    "triggerOnUpdates": true,
-    "updateExistingSummaryComment": true,
-    "updateSummaryOnly": false,
-    "issuesTableSection": {
-      "included": true,
-      "collapsible": false,
-      "defaultOpen": false
-    },
-    "statusCommentsEnabled": true,
-    "confidenceScoreSection": {
-      "included": true,
-      "collapsible": false
-    },
-    "sequenceDiagramSection": {
-      "included": true,
-      "collapsible": false,
-      "defaultOpen": false
-    },
-    "shouldUpdateDescription": false,
-    "customContext": {
-      "other": [
-        {
-          "scope": [],
-          "content": "Use explicit type annotations for variables to enhance code clarity, especially when moving type hints around in the code."
-        },
-        {
-          "scope": [],
-          "content": "Use `contributing_guides/best_practices.md` as core review context. Prefer consistency with existing patterns, fix issues in code you touch, avoid tacking new features onto muddy interfaces, fail loudly instead of silently swallowing errors, keep code strictly typed, preserve clear state boundaries, remove duplicate or dead logic, break up overly long functions, avoid hidden import-time side effects, respect module boundaries, and favor correctness-by-construction over relying on callers to use an API correctly."
-        }
-      ],
-      "rules": [
-        {
-          "scope": [],
-          "rule": "Whenever a TODO is added, there must always be an associated name or ticket with that TODO in the style of TODO(name): ... or TODO(1234): ..."
-        },
-        {
-          "scope": ["web/**"],
-          "rule": "For frontend changes (changes that touch the /web directory), make sure to enforce all standards described in the web/AGENTS.md file."
-        },
-        {
-          "scope": [],
-          "rule": "Remove temporary debugging code before merging to production, especially tenant-specific debugging logs."
-        },
-        {
-          "scope": [],
-          "rule": "When hardcoding a boolean variable to a constant value, remove the variable entirely and clean up all places where it's used rather than just setting it to a constant."
-        },
-        {
-          "scope": [],
-          "rule": "Code changes must consider both multi-tenant and single-tenant deployments. In multi-tenant mode, preserve tenant isolation, ensure tenant context is propagated correctly, and avoid assumptions that only hold for a single shared schema or globally shared state. In single-tenant mode, avoid introducing unnecessary tenant-specific requirements or cloud-only control-plane dependencies."
-        },
-        {
-          "scope": [],
-          "rule": "Code changes must consider both regular Onyx deployments and Onyx lite deployments. Lite deployments disable the vector DB, Redis, model servers, and background workers by default, use PostgreSQL-backed cache/auth/file storage, and rely on the API server to handle background work. Do not assume those services are available unless the code path is explicitly limited to full deployments."
-        },
-        {
-          "scope": ["web/**"],
-          "rule": "In Onyx's Next.js app, the `app/ee/admin/` directory is a filesystem convention for Enterprise Edition route overrides — it does NOT add an `/ee/` prefix to the URL. Both `app/admin/groups/page.tsx` and `app/ee/admin/groups/page.tsx` serve the same URL `/admin/groups`. Hardcoded `/admin/...` paths in router.push() calls are correct and do NOT break EE deployments. Do not flag hardcoded admin paths as bugs."
-        },
-        {
-          "scope": ["web/**"],
-          "rule": "In Onyx, each API key creates a unique user row in the database with a unique `user_id` (UUID). There is a 1:1 mapping between API keys and their backing user records. Multiple API keys do NOT share the same `user_id`. Do not flag potential duplicate row IDs when using `user_id` from API key descriptors."
-        },
-        {
-          "scope": ["backend/**/*.py"],
-          "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"detail\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
-        }
-      ],
-      "files": [
-        {
-          "scope": [],
-          "path": "contributing_guides/best_practices.md",
-          "description": "Best practices for contributing to the codebase"
-        },
-        {
-          "scope": [],
-          "path": "CLAUDE.md",
-          "description": "Project instructions and coding standards"
-        },
-        {
-          "scope": [],
-          "path": "backend/alembic/README.md",
-          "description": "Migration guidance, including multi-tenant migration behavior"
-        },
-        {
-          "scope": [],
-          "path": "deployment/helm/charts/onyx/values-lite.yaml",
-          "description": "Lite deployment Helm values and service assumptions"
-        },
-        {
-          "scope": [],
-          "path": "deployment/docker_compose/docker-compose.onyx-lite.yml",
-          "description": "Lite deployment Docker Compose overlay and disabled service behavior"
-        }
-      ]
-    }
-  }
-  

web/AGENTS.md

@@ -342,9 +342,9 @@ visible text in the DOM (e.g., `title`, `description`, `label`) should be typed
 
 ```typescript
 import type { RichStr } from "@opal/types";
-import { resolveStr } from "@opal/components/text/InlineMarkdown";
+import { Text } from "@opal/components";
 
-// ✅ Good — new components accept string | RichStr
+// ✅ Good — new components accept string | RichStr and render via Text
 interface InfoCardProps {
   title: string | RichStr;
   description?: string | RichStr;
@@ -353,9 +353,9 @@ interface InfoCardProps {
 function InfoCard({ title, description }: InfoCardProps) {
   return (
     <div>
-      <Text font="main-ui-action">{resolveStr(title)}</Text>
+      <Text font="main-ui-action">{title}</Text>
       {description && (
-        <Text font="secondary-body" color="text-03">{resolveStr(description)}</Text>
+        <Text font="secondary-body" color="text-03">{description}</Text>
       )}
     </div>
   );

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

@@ -4,11 +4,15 @@ import {
   Interactive,
   type InteractiveStatelessProps,
 } from "@opal/core";
-import type { ContainerSizeVariants, ExtremaSizeVariants } from "@opal/types";
+import type {
+  ContainerSizeVariants,
+  ExtremaSizeVariants,
+  RichStr,
+} from "@opal/types";
+import { Text } from "@opal/components";
 import type { TooltipSide } from "@opal/components";
 import type { IconFunctionComponent } from "@opal/types";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
-import { cn } from "@opal/utils";
 import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
 
 // ---------------------------------------------------------------------------
@@ -18,13 +22,13 @@ import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
 type ButtonContentProps =
   | {
       icon?: IconFunctionComponent;
-      children: string;
+      children: string | RichStr;
       rightIcon?: IconFunctionComponent;
       responsiveHideText?: never;
     }
   | {
       icon: IconFunctionComponent;
-      children?: string;
+      children?: string | RichStr;
       rightIcon?: IconFunctionComponent;
       responsiveHideText?: boolean;
     };
@@ -69,15 +73,24 @@ function Button({
   const isLarge = size === "lg";
 
   const labelEl = children ? (
-    <span
-      className={cn(
-        "whitespace-nowrap",
-        isLarge ? "font-main-ui-body " : "font-secondary-body",
-        responsiveHideText && "hidden md:inline"
-      )}
-    >
-      {children}
-    </span>
+    responsiveHideText ? (
+      <span className="hidden md:inline whitespace-nowrap">
+        <Text
+          font={isLarge ? "main-ui-body" : "secondary-body"}
+          color="inherit"
+        >
+          {children}
+        </Text>
+      </span>
+    ) : (
+      <Text
+        font={isLarge ? "main-ui-body" : "secondary-body"}
+        color="inherit"
+        nowrap
+      >
+        {children}
+      </Text>
+    )
   ) : null;
 
   const button = (

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

@@ -4,7 +4,8 @@ import {
   type InteractiveStatefulProps,
 } from "@opal/core";
 import type { TooltipSide } from "@opal/components";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import { Text } from "@opal/components";
 import { SvgX } from "@opal/icons";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
@@ -16,12 +17,12 @@ import { Button } from "@opal/components/buttons/button/components";
 // ---------------------------------------------------------------------------
 
 interface FilterButtonProps
-  extends Omit<InteractiveStatefulProps, "variant" | "state"> {
+  extends Omit<InteractiveStatefulProps, "variant" | "state" | "children"> {
   /** Left icon — always visible. */
   icon: IconFunctionComponent;
 
   /** Label text between icon and trailing indicator. */
-  children: string;
+  children: string | RichStr;
 
   /** Whether the filter has an active selection. @default false */
   active?: boolean;
@@ -68,9 +69,9 @@ function FilterButton({
         <Interactive.Container type="button">
           <div className="interactive-foreground flex flex-row items-center gap-1">
             {iconWrapper(Icon, "lg", true)}
-            <span className="whitespace-nowrap font-main-ui-action">
+            <Text font="main-ui-action" color="inherit" nowrap>
               {children}
-            </span>
+            </Text>
             <div style={{ visibility: active ? "hidden" : "visible" }}>
               {iconWrapper(ChevronIcon, "lg", true)}
             </div>

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

@@ -4,7 +4,12 @@ import {
   type InteractiveStatefulProps,
   type InteractiveStatefulInteraction,
 } from "@opal/core";
-import type { ContainerSizeVariants, ExtremaSizeVariants } from "@opal/types";
+import type {
+  ContainerSizeVariants,
+  ExtremaSizeVariants,
+  RichStr,
+} from "@opal/types";
+import { Text } from "@opal/components";
 import type { InteractiveContainerRoundingVariant } from "@opal/core";
 import type { TooltipSide } from "@opal/components";
 import type { IconFunctionComponent } from "@opal/types";
@@ -28,17 +33,17 @@ type OpenButtonContentProps =
   | {
       foldable: true;
       icon: IconFunctionComponent;
-      children: string;
+      children: string | RichStr;
     }
   | {
       foldable?: false;
       icon?: IconFunctionComponent;
-      children: string;
+      children: string | RichStr;
     }
   | {
       foldable?: false;
       icon: IconFunctionComponent;
-      children?: string;
+      children?: string | RichStr;
     };
 
 type OpenButtonVariant = "select-light" | "select-heavy" | "select-tinted";
@@ -101,14 +106,13 @@ function OpenButton({
   const isLarge = size === "lg";
 
   const labelEl = children ? (
-    <span
-      className={cn(
-        "whitespace-nowrap",
-        isLarge ? "font-main-ui-body" : "font-secondary-body"
-      )}
+    <Text
+      font={isLarge ? "main-ui-body" : "secondary-body"}
+      color="inherit"
+      nowrap
     >
       {children}
-    </span>
+    </Text>
   ) : null;
 
   const button = (
@@ -177,7 +181,7 @@ function OpenButton({
           side={tooltipSide}
           sideOffset={4}
         >
-          {resolvedTooltip}
+          <Text>{resolvedTooltip}</Text>
         </TooltipPrimitive.Content>
       </TooltipPrimitive.Portal>
     </TooltipPrimitive.Root>

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

@@ -4,7 +4,12 @@ import {
   useDisabled,
   type InteractiveStatefulProps,
 } from "@opal/core";
-import type { ContainerSizeVariants, ExtremaSizeVariants } from "@opal/types";
+import type {
+  ContainerSizeVariants,
+  ExtremaSizeVariants,
+  RichStr,
+} from "@opal/types";
+import { Text } from "@opal/components";
 import type { TooltipSide } from "@opal/components";
 import type { IconFunctionComponent } from "@opal/types";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
@@ -26,19 +31,19 @@ type SelectButtonContentProps =
   | {
       foldable: true;
       icon: IconFunctionComponent;
-      children: string;
+      children: string | RichStr;
       rightIcon?: IconFunctionComponent;
     }
   | {
       foldable?: false;
       icon?: IconFunctionComponent;
-      children: string;
+      children: string | RichStr;
       rightIcon?: IconFunctionComponent;
     }
   | {
       foldable?: false;
       icon: IconFunctionComponent;
-      children?: string;
+      children?: string | RichStr;
       rightIcon?: IconFunctionComponent;
     };
 
@@ -79,13 +84,10 @@ function SelectButton({
   const isLarge = size === "lg";
 
   const labelEl = children ? (
-    <span
-      className={cn(
-        "opal-select-button-label",
-        isLarge ? "font-main-ui-body" : "font-secondary-body"
-      )}
-    >
-      {children}
+    <span className="opal-select-button-label">
+      <Text font={isLarge ? "main-ui-body" : "secondary-body"} color="inherit">
+        {children}
+      </Text>
     </span>
   ) : null;
 
@@ -137,7 +139,7 @@ function SelectButton({
           side={tooltipSide}
           sideOffset={4}
         >
-          {resolvedTooltip}
+          <Text>{resolvedTooltip}</Text>
         </TooltipPrimitive.Content>
       </TooltipPrimitive.Portal>
     </TooltipPrimitive.Root>

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

@@ -4,7 +4,9 @@ import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
 import { SvgArrowRight, SvgChevronLeft, SvgChevronRight } from "@opal/icons";
 import { containerSizeVariants } from "@opal/shared";
-import type { WithoutStyles } from "@opal/types";
+import type { RichStr, WithoutStyles } from "@opal/types";
+import { Text } from "@opal/components";
+import { toPlainString } from "@opal/components/text/InlineMarkdown";
 import { cn } from "@opal/utils";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import {
@@ -38,7 +40,7 @@ interface SimplePaginationProps
   /** Hides the `currentPage/totalPages` summary text between arrows. Default: `false`. */
   hidePages?: boolean;
   /** Unit label shown after the summary (e.g. `"pages"`). Always has 4px spacing. */
-  units?: string;
+  units?: string | RichStr;
 }
 
 /**
@@ -63,7 +65,7 @@ interface CountPaginationProps
   /** Hides the current page number between the arrows. Default: `false`. */
   hidePages?: boolean;
   /** Unit label shown after the total count (e.g. `"items"`). Always has 4px spacing. */
-  units?: string;
+  units?: string | RichStr;
 }
 
 /**
@@ -331,7 +333,9 @@ function PaginationSimple({
 }: SimplePaginationProps) {
   const handleChange = (page: number) => onChange?.(page);
 
-  const label = `${currentPage}/${totalPages}${units ? ` ${units}` : ""}`;
+  const label = `${currentPage}/${totalPages}${
+    units ? ` ${toPlainString(units)}` : ""
+  }`;
 
   return (
     <div {...props} className="flex items-center">
@@ -385,7 +389,16 @@ function PaginationCount({
         {rangeStart}~{rangeEnd}
         <span className={textClasses(size, "muted")}>of</span>
         {totalItems}
-        {units && <span className="ml-1">{units}</span>}
+        {units && (
+          <span className="ml-1">
+            <Text
+              color="inherit"
+              font={size === "sm" ? "secondary-body" : "main-ui-muted"}
+            >
+              {units}
+            </Text>
+          </span>
+        )}
       </span>
 
       {/* Buttons: < [page] > */}

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

@@ -1,6 +1,7 @@
 import "@opal/components/tag/styles.css";
 
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import { Text } from "@opal/components";
 import { cn } from "@opal/utils";
 
 // ---------------------------------------------------------------------------
@@ -16,7 +17,7 @@ interface TagProps {
   icon?: IconFunctionComponent;
 
   /** Tag label text. */
-  title: string;
+  title: string | RichStr;
 
   /** Color variant. Default: `"gray"`. */
   color?: TagColor;
@@ -51,14 +52,13 @@ function Tag({ icon: Icon, title, color = "gray", size = "sm" }: TagProps) {
           <Icon className={cn("opal-auxiliary-tag-icon", config.text)} />
         </div>
       )}
-      <span
-        className={cn(
-          "opal-auxiliary-tag-title px-[2px]",
-          size === "md" ? "font-secondary-body" : "font-figure-small-value",
-          config.text
-        )}
-      >
-        {title}
+      <span className={cn("opal-auxiliary-tag-title px-[2px]", config.text)}>
+        <Text
+          font={size === "md" ? "secondary-body" : "figure-small-value"}
+          color="inherit"
+        >
+          {title}
+        </Text>
       </span>
     </div>
   );

web/lib/opal/src/components/text/InlineMarkdown.tsx

@@ -10,7 +10,7 @@ import type { RichStr } from "@opal/types";
 
 const SAFE_PROTOCOL = /^https?:|^mailto:|^tel:/i;
 
-const ALLOWED_ELEMENTS = ["p", "a", "strong", "em", "code", "del"];
+const ALLOWED_ELEMENTS = ["p", "br", "a", "strong", "em", "code", "del"];
 
 const INLINE_COMPONENTS = {
   p: ({ children }: { children?: ReactNode }) => <>{children}</>,
@@ -41,6 +41,11 @@ interface InlineMarkdownProps {
 }
 
 export default function InlineMarkdown({ content }: InlineMarkdownProps) {
+  // Convert \n to CommonMark hard line breaks (two trailing spaces + newline).
+  // react-markdown renders these as <br />, which inherits the parent's
+  // line-height for font-appropriate spacing.
+  const normalized = content.replace(/\n/g, "  \n");
+
   return (
     <ReactMarkdown
       components={INLINE_COMPONENTS}
@@ -48,7 +53,7 @@ export default function InlineMarkdown({ content }: InlineMarkdownProps) {
       unwrapDisallowed
       remarkPlugins={[remarkGfm]}
     >
-      {content}
+      {normalized}
     </ReactMarkdown>
   );
 }

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

@@ -90,15 +90,15 @@ import { markdown } from "@opal/utils";
 </Text>
 ```
 
-Supported syntax: `**bold**`, `*italic*`, `` `code` ``, `[link](url)`, `~~strikethrough~~`.
+Supported syntax: `**bold**`, `*italic*`, `` `code` ``, `[link](url)`, `~~strikethrough~~`, `\n` (newline → `<br />`).
 
 Markdown rendering uses `react-markdown` internally, restricted to inline elements only.
 `http(s)` links open in a new tab; `mailto:` and `tel:` links open natively. Inline code
 inherits the parent font size and switches to the monospace family.
 
-**Note:** This is inline-only markdown. Multi-paragraph content (`"Hello\n\nWorld"`) will
-collapse into a single run of text since paragraph wrappers are stripped. For block-level
-markdown, use `MinimalMarkdown` instead.
+Newlines (`\n`) are converted to `<br />` elements that inherit the parent's line-height,
+so line spacing is proportional to the font size. For full block-level markdown (code blocks,
+headings, lists), use `MinimalMarkdown` instead.
 
 ### Using `RichStr` in component props
 

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

@@ -29,6 +29,7 @@ type TextFont =
   | "figure-keystroke";
 
 type TextColor =
+  | "inherit"
   | "text-01"
   | "text-02"
   | "text-03"
@@ -60,6 +61,9 @@ interface TextProps
   /** Prevent text wrapping. */
   nowrap?: boolean;
 
+  /** Truncate text to N lines with ellipsis. `1` uses simple truncation; `2+` uses `-webkit-line-clamp`. */
+  maxLines?: number;
+
   /** Plain string or `markdown()` for inline markdown. */
   children?: string | RichStr;
 }
@@ -89,7 +93,8 @@ const FONT_CONFIG: Record<TextFont, string> = {
   "figure-keystroke": "font-figure-keystroke",
 };
 
-const COLOR_CONFIG: Record<TextColor, string> = {
+const COLOR_CONFIG: Record<TextColor, string | null> = {
+  inherit: null,
   "text-01": "text-text-01",
   "text-02": "text-text-02",
   "text-03": "text-text-03",
@@ -115,17 +120,29 @@ function Text({
   color = "text-04",
   as: Tag = "span",
   nowrap,
+  maxLines,
   children,
   ...rest
 }: TextProps) {
   const resolvedClassName = cn(
     FONT_CONFIG[font],
     COLOR_CONFIG[color],
-    nowrap && "whitespace-nowrap"
+    nowrap && "whitespace-nowrap",
+    maxLines === 1 && "truncate",
+    maxLines && maxLines > 1 && "overflow-hidden"
   );
 
+  const style =
+    maxLines && maxLines > 1
+      ? ({
+          display: "-webkit-box",
+          WebkitBoxOrient: "vertical",
+          WebkitLineClamp: maxLines,
+        } as React.CSSProperties)
+      : undefined;
+
   return (
-    <Tag {...rest} className={resolvedClassName}>
+    <Tag {...rest} className={resolvedClassName} style={style}>
       {children && resolveStr(children)}
     </Tag>
   );

web/lib/opal/src/core/animations/components.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import "@opal/core/animations/styles.css";
 import React, { createContext, useContext, useState, useCallback } from "react";
 import { cn } from "@opal/utils";

web/lib/opal/src/core/disabled/components.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import "@opal/core/disabled/styles.css";
 import React, { createContext, useContext } from "react";
 import { Slot } from "@radix-ui/react-slot";

web/lib/opal/src/icons/bifrost.tsx

@@ -0,0 +1,22 @@
+import { cn } from "@opal/utils";
+import type { IconProps } from "@opal/types";
+
+const SvgBifrost = ({ size, className, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 37 46"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    className={cn(className, "text-[#33C19E] dark:text-white")}
+    {...props}
+  >
+    <title>Bifrost</title>
+    <path
+      d="M27.6219 46H0V36.8H27.6219V46ZM36.8268 36.8H27.6219V27.6H36.8268V36.8ZM18.4146 27.6H9.2073V18.4H18.4146V27.6ZM36.8268 18.4H27.6219V9.2H36.8268V18.4ZM27.6219 9.2H0V0H27.6219V9.2Z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+export default SvgBifrost;

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

@@ -24,6 +24,7 @@ export { default as SvgAzure } from "@opal/icons/azure";
 export { default as SvgBarChart } from "@opal/icons/bar-chart";
 export { default as SvgBarChartSmall } from "@opal/icons/bar-chart-small";
 export { default as SvgBell } from "@opal/icons/bell";
+export { default as SvgBifrost } from "@opal/icons/bifrost";
 export { default as SvgBlocks } from "@opal/icons/blocks";
 export { default as SvgBookOpen } from "@opal/icons/book-open";
 export { default as SvgBookmark } from "@opal/icons/bookmark";

web/lib/opal/src/layouts/content/ContentLg.tsx

@@ -3,7 +3,11 @@
 import { Button } from "@opal/components/buttons/button/components";
 import type { ContainerSizeVariants } from "@opal/types";
 import SvgEdit from "@opal/icons/edit";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import {
+  resolveStr,
+  toPlainString,
+} from "@opal/components/text/InlineMarkdown";
 import { cn } from "@opal/utils";
 import { useState } from "react";
 
@@ -35,10 +39,10 @@ interface ContentLgProps {
   icon?: IconFunctionComponent;
 
   /** Main title text. */
-  title: string;
+  title: string | RichStr;
 
   /** Optional description below the title. */
-  description?: string;
+  description?: string | RichStr;
 
   /** Enable inline editing of the title. */
   editable?: boolean;
@@ -96,18 +100,18 @@ function ContentLg({
   ref,
 }: ContentLgProps) {
   const [editing, setEditing] = useState(false);
-  const [editValue, setEditValue] = useState(title);
+  const [editValue, setEditValue] = useState(toPlainString(title));
 
   const config = CONTENT_LG_PRESETS[sizePreset];
 
   function startEditing() {
-    setEditValue(title);
+    setEditValue(toPlainString(title));
     setEditing(true);
   }
 
   function commit() {
     const value = editValue.trim();
-    if (value && value !== title) onTitleChange?.(value);
+    if (value && value !== toPlainString(title)) onTitleChange?.(value);
     setEditing(false);
   }
 
@@ -157,7 +161,7 @@ function ContentLg({
                 onKeyDown={(e) => {
                   if (e.key === "Enter") commit();
                   if (e.key === "Escape") {
-                    setEditValue(title);
+                    setEditValue(toPlainString(title));
                     setEditing(false);
                   }
                 }}
@@ -174,9 +178,9 @@ function ContentLg({
               )}
               onClick={editable ? startEditing : undefined}
               style={{ height: config.lineHeight }}
-              title={title}
+              title={toPlainString(title)}
             >
-              {title}
+              {resolveStr(title)}
             </span>
           )}
 
@@ -199,9 +203,9 @@ function ContentLg({
           )}
         </div>
 
-        {description && (
+        {description && toPlainString(description) && (
           <div className="opal-content-lg-description font-secondary-body text-text-03">
-            {description}
+            {resolveStr(description)}
           </div>
         )}
       </div>

web/lib/opal/src/layouts/content/ContentMd.tsx

@@ -7,7 +7,11 @@ import SvgAlertCircle from "@opal/icons/alert-circle";
 import SvgAlertTriangle from "@opal/icons/alert-triangle";
 import SvgEdit from "@opal/icons/edit";
 import SvgXOctagon from "@opal/icons/x-octagon";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import {
+  resolveStr,
+  toPlainString,
+} from "@opal/components/text/InlineMarkdown";
 import { cn } from "@opal/utils";
 import { useRef, useState } from "react";
 
@@ -25,7 +29,6 @@ interface ContentMdPresetConfig {
   iconColorClass: string;
   titleFont: string;
   lineHeight: string;
-  gap: string;
   /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
   editButtonSize: ContainerSizeVariants;
   editButtonPadding: string;
@@ -41,10 +44,10 @@ interface ContentMdProps {
   icon?: IconFunctionComponent;
 
   /** Main title text. */
-  title: string;
+  title: string | RichStr;
 
   /** Optional description text below the title. */
-  description?: string;
+  description?: string | RichStr;
 
   /** Enable inline editing of the title. */
   editable?: boolean;
@@ -85,7 +88,6 @@ const CONTENT_MD_PRESETS: Record<ContentMdSizePreset, ContentMdPresetConfig> = {
     iconColorClass: "text-text-04",
     titleFont: "font-main-content-emphasis",
     lineHeight: "1.5rem",
-    gap: "0.125rem",
     editButtonSize: "sm",
     editButtonPadding: "p-0",
     optionalFont: "font-main-content-muted",
@@ -98,7 +100,6 @@ const CONTENT_MD_PRESETS: Record<ContentMdSizePreset, ContentMdPresetConfig> = {
     iconColorClass: "text-text-03",
     titleFont: "font-main-ui-action",
     lineHeight: "1.25rem",
-    gap: "0.25rem",
     editButtonSize: "xs",
     editButtonPadding: "p-0",
     optionalFont: "font-main-ui-muted",
@@ -111,7 +112,6 @@ const CONTENT_MD_PRESETS: Record<ContentMdSizePreset, ContentMdPresetConfig> = {
     iconColorClass: "text-text-04",
     titleFont: "font-secondary-action",
     lineHeight: "1rem",
-    gap: "0.125rem",
     editButtonSize: "2xs",
     editButtonPadding: "p-0",
     optionalFont: "font-secondary-action",
@@ -149,19 +149,19 @@ function ContentMd({
   ref,
 }: ContentMdProps) {
   const [editing, setEditing] = useState(false);
-  const [editValue, setEditValue] = useState(title);
+  const [editValue, setEditValue] = useState(toPlainString(title));
   const inputRef = useRef<HTMLInputElement>(null);
 
   const config = CONTENT_MD_PRESETS[sizePreset];
 
   function startEditing() {
-    setEditValue(title);
+    setEditValue(toPlainString(title));
     setEditing(true);
   }
 
   function commit() {
     const value = editValue.trim();
-    if (value && value !== title) onTitleChange?.(value);
+    if (value && value !== toPlainString(title)) onTitleChange?.(value);
     setEditing(false);
   }
 
@@ -170,7 +170,6 @@ function ContentMd({
       ref={ref}
       className="opal-content-md"
       data-interactive={withInteractive || undefined}
-      style={{ gap: config.gap }}
     >
       <div
         className="opal-content-md-header"
@@ -215,7 +214,7 @@ function ContentMd({
                 onKeyDown={(e) => {
                   if (e.key === "Enter") commit();
                   if (e.key === "Escape") {
-                    setEditValue(title);
+                    setEditValue(toPlainString(title));
                     setEditing(false);
                   }
                 }}
@@ -230,11 +229,11 @@ function ContentMd({
                 "text-text-04",
                 editable && "cursor-pointer"
               )}
-              title={title}
+              title={toPlainString(title)}
               onClick={editable ? startEditing : undefined}
               style={{ height: config.lineHeight }}
             >
-              {title}
+              {resolveStr(title)}
             </span>
           )}
 
@@ -288,12 +287,12 @@ function ContentMd({
         </div>
       </div>
 
-      {description && (
+      {description && toPlainString(description) && (
         <div
           className="opal-content-md-description font-secondary-body text-text-03"
           style={Icon ? { paddingLeft: config.descriptionIndent } : undefined}
         >
-          {description}
+          {resolveStr(description)}
         </div>
       )}
     </div>

web/lib/opal/src/layouts/content/ContentSm.tsx

@@ -1,6 +1,10 @@
 "use client";
 
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import {
+  resolveStr,
+  toPlainString,
+} from "@opal/components/text/InlineMarkdown";
 import { cn } from "@opal/utils";
 
 // ---------------------------------------------------------------------------
@@ -30,7 +34,7 @@ interface ContentSmProps {
   icon?: IconFunctionComponent;
 
   /** Main title text (read-only — editing is not supported). */
-  title: string;
+  title: string | RichStr;
 
   /** Size preset. Default: `"main-ui"`. */
   sizePreset?: ContentSmSizePreset;
@@ -118,9 +122,9 @@ function ContentSm({
       <span
         className={cn("opal-content-sm-title", config.titleFont)}
         style={{ height: config.lineHeight }}
-        title={title}
+        title={toPlainString(title)}
       >
-        {title}
+        {resolveStr(title)}
       </span>
     </div>
   );

web/lib/opal/src/layouts/content/ContentXl.tsx

@@ -3,7 +3,11 @@
 import { Button } from "@opal/components/buttons/button/components";
 import type { ContainerSizeVariants } from "@opal/types";
 import SvgEdit from "@opal/icons/edit";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import {
+  resolveStr,
+  toPlainString,
+} from "@opal/components/text/InlineMarkdown";
 import { cn } from "@opal/utils";
 import { useState } from "react";
 
@@ -41,10 +45,10 @@ interface ContentXlProps {
   icon?: IconFunctionComponent;
 
   /** Main title text. */
-  title: string;
+  title: string | RichStr;
 
   /** Optional description below the title. */
-  description?: string;
+  description?: string | RichStr;
 
   /** Enable inline editing of the title. */
   editable?: boolean;
@@ -116,18 +120,18 @@ function ContentXl({
   ref,
 }: ContentXlProps) {
   const [editing, setEditing] = useState(false);
-  const [editValue, setEditValue] = useState(title);
+  const [editValue, setEditValue] = useState(toPlainString(title));
 
   const config = CONTENT_XL_PRESETS[sizePreset];
 
   function startEditing() {
-    setEditValue(title);
+    setEditValue(toPlainString(title));
     setEditing(true);
   }
 
   function commit() {
     const value = editValue.trim();
-    if (value && value !== title) onTitleChange?.(value);
+    if (value && value !== toPlainString(title)) onTitleChange?.(value);
     setEditing(false);
   }
 
@@ -214,7 +218,7 @@ function ContentXl({
                 onKeyDown={(e) => {
                   if (e.key === "Enter") commit();
                   if (e.key === "Escape") {
-                    setEditValue(title);
+                    setEditValue(toPlainString(title));
                     setEditing(false);
                   }
                 }}
@@ -231,9 +235,9 @@ function ContentXl({
               )}
               onClick={editable ? startEditing : undefined}
               style={{ height: config.lineHeight }}
-              title={title}
+              title={toPlainString(title)}
             >
-              {title}
+              {resolveStr(title)}
             </span>
           )}
 
@@ -256,9 +260,9 @@ function ContentXl({
           )}
         </div>
 
-        {description && (
+        {description && toPlainString(description) && (
           <div className="opal-content-xl-description font-secondary-body text-text-03">
-            {description}
+            {resolveStr(description)}
           </div>
         )}
       </div>

web/lib/opal/src/layouts/content/components.tsx

@@ -1,3 +1,39 @@
+// ---------------------------------------------------------------------------
+// NOTE (@raunakab): Why Content uses resolveStr() instead of <Text>
+//
+// Content sub-components (ContentXl, ContentLg, ContentMd, ContentSm) render
+// titles and descriptions inside styled <span> elements that carry CSS classes
+// (e.g., `.opal-content-md-title`) for:
+//
+//   1. Truncation — `-webkit-box` + `-webkit-line-clamp` for single-line
+//      clamping with ellipsis. This requires the text to be a DIRECT child
+//      of the `-webkit-box` element. Wrapping it in a child <span> (which
+//      is what <Text> renders) breaks the clamping behavior.
+//
+//   2. Pixel-exact sizing — the wrapper <span> has an explicit `height`
+//      matching the font's `line-height`. Adding a child <Text> <span>
+//      inside creates a double-span where the inner element's line-height
+//      conflicts with the outer element's height, causing a ~4px vertical
+//      offset.
+//
+//   3. Interactive color overrides — CSS selectors like
+//      `.opal-content-md[data-interactive] .opal-content-md-title` set
+//      `color: var(--interactive-foreground)`. <Text> with `color="inherit"`
+//      can inherit this, but <Text> with any explicit color prop overrides
+//      it. And the wrapper <span> needs the CSS class for the selector to
+//      match — removing it breaks the cascade.
+//
+//   4. Horizontal padding — the title CSS class applies `padding: 0 0.125rem`
+//      (2px). Since <Text> uses WithoutStyles (no className/style), this
+//      padding cannot be applied to <Text> directly. A wrapper <div> was
+//      attempted but introduced additional layout conflicts.
+//
+// For these reasons, Content uses `resolveStr()` from InlineMarkdown.tsx to
+// handle `string | RichStr` rendering. `resolveStr()` returns a ReactNode
+// that slots directly into the existing single <span> — no extra wrapper,
+// no layout conflicts, pixel-exact match with main.
+// ---------------------------------------------------------------------------
+
 import "@opal/layouts/content/styles.css";
 import {
   ContentSm,
@@ -17,7 +53,7 @@ import {
   type ContentMdProps,
 } from "@opal/layouts/content/ContentMd";
 import type { TagProps } from "@opal/components/tag/components";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
 import { widthVariants } from "@opal/shared";
 import type { ExtremaSizeVariants } from "@opal/types";
 
@@ -39,10 +75,10 @@ interface ContentBaseProps {
   icon?: IconFunctionComponent;
 
   /** Main title text. */
-  title: string;
+  title: string | RichStr;
 
   /** Optional description below the title. */
-  description?: string;
+  description?: string | RichStr;
 
   /** Enable inline editing of the title. */
   editable?: boolean;

web/lib/opal/src/layouts/illustration-content/components.tsx

@@ -1,4 +1,5 @@
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
+import { Text } from "@opal/components";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -9,10 +10,10 @@ interface IllustrationContentProps {
   illustration?: IconFunctionComponent;
 
   /** Main title text, center-aligned. Uses `font-main-content-emphasis`. */
-  title: string;
+  title: string | RichStr;
 
   /** Optional description below the title, center-aligned. Uses `font-secondary-body`. */
-  description?: string;
+  description?: string | RichStr;
 }
 
 // ---------------------------------------------------------------------------
@@ -68,9 +69,13 @@ function IllustrationContent({
         />
       )}
       <div className="flex flex-col items-center text-center">
-        <p className="font-main-content-emphasis text-text-04">{title}</p>
+        <Text font="main-content-emphasis" color="text-04" as="p">
+          {title}
+        </Text>
         {description && (
-          <p className="font-secondary-body text-text-03">{description}</p>
+          <Text font="secondary-body" color="text-03" as="p">
+            {description}
+          </Text>
         )}
       </div>
     </div>

web/src/app/admin/api-key/page.tsx

@@ -30,8 +30,11 @@ import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { Button } from "@opal/components";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import Text from "@/refresh-components/texts/Text";
-import { SvgEdit, SvgInfo, SvgKey, SvgRefreshCw } from "@opal/icons";
+import { SvgEdit, SvgKey, SvgRefreshCw } from "@opal/icons";
+import Message from "@/refresh-components/messages/Message";
 import { useCloudSubscription } from "@/hooks/useCloudSubscription";
+import { useBillingInformation } from "@/hooks/useBillingInformation";
+import { BillingStatus, hasActiveSubscription } from "@/lib/billing/interfaces";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 
 const route = ADMIN_ROUTES.API_KEYS;
@@ -44,6 +47,11 @@ function Main() {
   } = useSWR<APIKey[]>("/api/admin/api-key", errorHandlingFetcher);
 
   const canCreateKeys = useCloudSubscription();
+  const { data: billingData } = useBillingInformation();
+  const isTrialing =
+    billingData !== undefined &&
+    hasActiveSubscription(billingData) &&
+    billingData.status === BillingStatus.TRIALING;
 
   const [fullApiKey, setFullApiKey] = useState<string | null>(null);
   const [keyIsGenerating, setKeyIsGenerating] = useState(false);
@@ -75,6 +83,16 @@ function Main() {
 
   const introSection = (
     <div className="flex flex-col items-start gap-4">
+      {isTrialing && (
+        <Message
+          static
+          warning
+          close={false}
+          className="w-full"
+          text="Upgrade to a paid plan to create API keys."
+          description="Trial accounts do not include API key access — purchase a paid subscription to unlock this feature."
+        />
+      )}
       <Text as="p">
         API Keys allow you to access Onyx APIs programmatically.
         {canCreateKeys
@@ -85,23 +103,9 @@ function Main() {
         <CreateButton onClick={() => setShowCreateUpdateForm(true)}>
           Create API Key
         </CreateButton>
-      ) : (
-        <div className="flex flex-col gap-2 rounded-lg bg-background-tint-02 p-4">
-          <div className="flex items-center gap-1.5">
-            <Text as="p" text04>
-              Upgrade to a paid plan to create API keys.
-            </Text>
-            <Button
-              variant="none"
-              prominence="tertiary"
-              size="2xs"
-              icon={SvgInfo}
-              tooltip="API keys enable programmatic access to Onyx for service accounts and integrations. Trial accounts do not include API key access — purchase a paid subscription to unlock this feature."
-            />
-          </div>
-          <Button href="/admin/billing">Upgrade to Paid Plan</Button>
-        </div>
-      )}
+      ) : isTrialing ? (
+        <Button href="/admin/billing">Upgrade to Paid Plan</Button>
+      ) : null}
     </div>
   );
 

web/src/app/admin/billing/page.test.tsx

@@ -0,0 +1,387 @@
+/**
+ * Tests for BillingPage handleBillingReturn retry logic.
+ *
+ * The retry logic retries claimLicense up to 3 times with 2s backoff
+ * when returning from a Stripe checkout session. This prevents the user
+ * from getting stranded when the Stripe webhook fires concurrently with
+ * the browser redirect and the license isn't ready yet.
+ */
+import React from "react";
+import { render, screen, waitFor } from "@tests/setup/test-utils";
+import { act } from "@testing-library/react";
+
+// ---- Stable mock objects (must be named with mock* prefix for jest hoisting) ----
+// useRouter and useSearchParams must return the SAME reference each call, otherwise
+// React's useEffect sees them as changed and re-runs the effect on every render.
+const mockRouter = {
+  replace: jest.fn() as jest.Mock,
+  refresh: jest.fn() as jest.Mock,
+};
+const mockSearchParams = {
+  get: jest.fn() as jest.Mock,
+};
+const mockClaimLicense = jest.fn() as jest.Mock;
+const mockRefreshBilling = jest.fn() as jest.Mock;
+const mockRefreshLicense = jest.fn() as jest.Mock;
+
+// ---- Mocks ----
+
+jest.mock("next/navigation", () => ({
+  useRouter: () => mockRouter,
+  useSearchParams: () => mockSearchParams,
+}));
+
+jest.mock("@/layouts/settings-layouts", () => ({
+  Root: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="settings-root">{children}</div>
+  ),
+  Header: () => <div data-testid="settings-header" />,
+  Body: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="settings-body">{children}</div>
+  ),
+}));
+
+jest.mock("@/layouts/general-layouts", () => ({
+  Section: ({ children }: { children: React.ReactNode }) => (
+    <div>{children}</div>
+  ),
+}));
+
+jest.mock("@opal/icons", () => ({
+  SvgArrowUpCircle: () => <svg />,
+  SvgWallet: () => <svg />,
+}));
+
+jest.mock("./PlansView", () => ({
+  __esModule: true,
+  default: () => <div data-testid="plans-view" />,
+}));
+jest.mock("./CheckoutView", () => ({
+  __esModule: true,
+  default: () => <div data-testid="checkout-view" />,
+}));
+jest.mock("./BillingDetailsView", () => ({
+  __esModule: true,
+  default: () => <div data-testid="billing-details-view" />,
+}));
+jest.mock("./LicenseActivationCard", () => ({
+  __esModule: true,
+  default: () => <div data-testid="license-activation-card" />,
+}));
+
+jest.mock("@/refresh-components/messages/Message", () => ({
+  __esModule: true,
+  default: ({
+    text,
+    description,
+    onClose,
+  }: {
+    text: string;
+    description?: string;
+    onClose?: () => void;
+  }) => (
+    <div data-testid="activating-banner">
+      <span data-testid="activating-banner-text">{text}</span>
+      {description && (
+        <span data-testid="activating-banner-description">{description}</span>
+      )}
+      {onClose && (
+        <button data-testid="activating-banner-close" onClick={onClose}>
+          Close
+        </button>
+      )}
+    </div>
+  ),
+}));
+
+jest.mock("@/lib/billing", () => ({
+  useBillingInformation: jest.fn(),
+  useLicense: jest.fn(),
+  hasActiveSubscription: jest.fn().mockReturnValue(false),
+  claimLicense: (...args: unknown[]) => mockClaimLicense(...args),
+}));
+
+jest.mock("@/lib/constants", () => ({
+  NEXT_PUBLIC_CLOUD_ENABLED: false,
+}));
+
+// ---- Import after mocks ----
+import BillingPage from "./page";
+import { useBillingInformation, useLicense } from "@/lib/billing";
+
+// ---- Test helpers ----
+
+function setupHooks() {
+  (useBillingInformation as jest.Mock).mockReturnValue({
+    data: null,
+    isLoading: false,
+    error: null,
+    refresh: mockRefreshBilling,
+  });
+  (useLicense as jest.Mock).mockReturnValue({
+    data: null,
+    isLoading: false,
+    refresh: mockRefreshLicense,
+  });
+}
+
+// ---- Tests ----
+
+describe("BillingPage — handleBillingReturn retry logic", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+    setupHooks();
+    // Default: no billing-return params
+    mockSearchParams.get.mockReturnValue(null);
+    // Clear any activating state from prior tests
+    sessionStorage.clear();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  test("calls claimLicense once and refreshes on first-attempt success", async () => {
+    mockSearchParams.get.mockImplementation((key: string) =>
+      key === "session_id" ? "cs_test_123" : null
+    );
+    mockClaimLicense.mockResolvedValueOnce({ success: true });
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    await waitFor(() => {
+      expect(mockClaimLicense).toHaveBeenCalledTimes(1);
+      expect(mockClaimLicense).toHaveBeenCalledWith("cs_test_123");
+    });
+    expect(mockRouter.refresh).toHaveBeenCalled();
+    expect(mockRefreshBilling).toHaveBeenCalled();
+    // URL cleaned up after checkout return
+    expect(mockRouter.replace).toHaveBeenCalledWith("/admin/billing", {
+      scroll: false,
+    });
+  });
+
+  test("retries after first failure and succeeds on second attempt", async () => {
+    mockSearchParams.get.mockImplementation((key: string) =>
+      key === "session_id" ? "cs_retry_test" : null
+    );
+    mockClaimLicense
+      .mockRejectedValueOnce(new Error("License not ready yet"))
+      .mockResolvedValueOnce({ success: true });
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    await waitFor(() => {
+      expect(mockClaimLicense).toHaveBeenCalledTimes(2);
+    });
+    // On eventual success, router and billing should be refreshed
+    expect(mockRouter.refresh).toHaveBeenCalled();
+    expect(mockRefreshBilling).toHaveBeenCalled();
+  });
+
+  test("retries all 3 times then navigates to details even on total failure", async () => {
+    mockSearchParams.get.mockImplementation((key: string) =>
+      key === "session_id" ? "cs_all_fail" : null
+    );
+    // All 3 attempts fail
+    mockClaimLicense.mockRejectedValue(new Error("Webhook not processed yet"));
+
+    const consoleSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    await waitFor(() => {
+      expect(mockClaimLicense).toHaveBeenCalledTimes(3);
+    });
+    // User stays on plans view with the activating banner
+    await waitFor(() => {
+      expect(screen.getByTestId("plans-view")).toBeInTheDocument();
+    });
+    // refreshBilling still fires so billing state is up to date
+    expect(mockRefreshBilling).toHaveBeenCalled();
+    // Failure is logged
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to sync license after billing return"),
+      expect.any(Error)
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  test("calls claimLicense without session_id on portal_return", async () => {
+    mockSearchParams.get.mockImplementation((key: string) =>
+      key === "portal_return" ? "true" : null
+    );
+    mockClaimLicense.mockResolvedValueOnce({ success: true });
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    await waitFor(() => {
+      expect(mockClaimLicense).toHaveBeenCalledTimes(1);
+      // No session_id for portal returns — called with undefined
+      expect(mockClaimLicense).toHaveBeenCalledWith(undefined);
+    });
+    expect(mockRefreshBilling).toHaveBeenCalled();
+  });
+
+  test("does not call claimLicense when no billing-return params present", async () => {
+    mockSearchParams.get.mockReturnValue(null);
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    expect(mockClaimLicense).not.toHaveBeenCalled();
+  });
+
+  test("shows activating banner and sets sessionStorage on 3x retry failure", async () => {
+    mockSearchParams.get.mockImplementation((key: string) =>
+      key === "session_id" ? "cs_all_fail" : null
+    );
+    mockClaimLicense.mockRejectedValue(new Error("Webhook not processed yet"));
+
+    const consoleSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("activating-banner")).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("activating-banner-text")).toHaveTextContent(
+      "Your license is still activating"
+    );
+    expect(
+      sessionStorage.getItem("billing_license_activating_until")
+    ).not.toBeNull();
+
+    consoleSpy.mockRestore();
+  });
+
+  test("banner not rendered when no activating state", async () => {
+    mockSearchParams.get.mockReturnValue(null);
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    expect(screen.queryByTestId("activating-banner")).not.toBeInTheDocument();
+  });
+
+  test("banner shown on mount when sessionStorage key is set and not expired", async () => {
+    sessionStorage.setItem(
+      "billing_license_activating_until",
+      String(Date.now() + 120_000)
+    );
+    mockSearchParams.get.mockReturnValue(null);
+
+    render(<BillingPage />);
+
+    // Flush React effects — banner is visible from lazy state init, no timer advancement needed
+    await act(async () => {});
+
+    expect(screen.getByTestId("activating-banner")).toBeInTheDocument();
+  });
+
+  test("banner not shown on mount when sessionStorage key is expired", async () => {
+    sessionStorage.setItem(
+      "billing_license_activating_until",
+      String(Date.now() - 1000)
+    );
+    mockSearchParams.get.mockReturnValue(null);
+
+    render(<BillingPage />);
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    expect(screen.queryByTestId("activating-banner")).not.toBeInTheDocument();
+    expect(
+      sessionStorage.getItem("billing_license_activating_until")
+    ).toBeNull();
+  });
+
+  test("poll calls claimLicense after 15s and clears banner on success", async () => {
+    sessionStorage.setItem(
+      "billing_license_activating_until",
+      String(Date.now() + 120_000)
+    );
+    mockSearchParams.get.mockReturnValue(null);
+    // Poll attempt succeeds
+    mockClaimLicense.mockResolvedValueOnce({ success: true });
+
+    render(<BillingPage />);
+
+    // Flush effects — banner visible from lazy state init
+    await act(async () => {});
+    expect(screen.getByTestId("activating-banner")).toBeInTheDocument();
+
+    // Advance past one poll interval (15s)
+    await act(async () => {
+      await jest.advanceTimersByTimeAsync(15_000);
+    });
+
+    expect(mockClaimLicense).toHaveBeenCalledWith(undefined);
+    expect(screen.queryByTestId("activating-banner")).not.toBeInTheDocument();
+    expect(
+      sessionStorage.getItem("billing_license_activating_until")
+    ).toBeNull();
+    expect(mockRefreshBilling).toHaveBeenCalled();
+    expect(mockRefreshLicense).toHaveBeenCalled();
+    expect(mockRouter.refresh).toHaveBeenCalled();
+  });
+
+  test("close button removes banner and clears sessionStorage", async () => {
+    sessionStorage.setItem(
+      "billing_license_activating_until",
+      String(Date.now() + 120_000)
+    );
+    mockSearchParams.get.mockReturnValue(null);
+
+    render(<BillingPage />);
+
+    // Flush effects — banner visible from lazy state init
+    await act(async () => {});
+    expect(screen.getByTestId("activating-banner")).toBeInTheDocument();
+
+    const closeButton = screen.getByTestId("activating-banner-close");
+    await act(async () => {
+      closeButton.click();
+    });
+
+    expect(screen.queryByTestId("activating-banner")).not.toBeInTheDocument();
+    expect(
+      sessionStorage.getItem("billing_license_activating_until")
+    ).toBeNull();
+  });
+});

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

@@ -17,6 +17,7 @@ import {
 } from "@/lib/billing";
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
 import { useUser } from "@/providers/UserProvider";
+import Message from "@/refresh-components/messages/Message";
 
 import PlansView from "./PlansView";
 import CheckoutView from "./CheckoutView";
@@ -24,6 +25,9 @@ import BillingDetailsView from "./BillingDetailsView";
 import LicenseActivationCard from "./LicenseActivationCard";
 import "./billing.css";
 
+// sessionStorage key: value is a unix-ms expiry timestamp
+const BILLING_ACTIVATING_KEY = "billing_license_activating_until";
+
 // ----------------------------------------------------------------------------
 // Types
 // ----------------------------------------------------------------------------
@@ -105,6 +109,7 @@ export default function BillingPage() {
   const [transitionType, setTransitionType] = useState<
     "expand" | "collapse" | "fade"
   >("fade");
+  const [isActivating, setIsActivating] = useState<boolean>(false);
 
   const {
     data: billingData,
@@ -155,6 +160,17 @@ export default function BillingPage() {
     view,
   ]);
 
+  // Read activating state from sessionStorage after mount (avoids SSR hydration mismatch)
+  useEffect(() => {
+    const raw = sessionStorage.getItem(BILLING_ACTIVATING_KEY);
+    if (!raw) return;
+    if (Number(raw) > Date.now()) {
+      setIsActivating(true);
+    } else {
+      sessionStorage.removeItem(BILLING_ACTIVATING_KEY);
+    }
+  }, []);
+
   // Show license activation card when there's a Stripe error
   useEffect(() => {
     if (hasStripeError && !showLicenseActivationInput) {
@@ -172,24 +188,96 @@ export default function BillingPage() {
 
     router.replace("/admin/billing", { scroll: false });
 
+    let cancelled = false;
+
     const handleBillingReturn = async () => {
       if (!NEXT_PUBLIC_CLOUD_ENABLED) {
-        try {
-          // After checkout, exchange session_id for license; after portal, re-sync license
-          await claimLicense(sessionId ?? undefined);
-          refreshLicense();
-          // Refresh the page to update settings (including ee_features_enabled)
-          router.refresh();
-          // Navigate to billing details now that the license is active
-          changeView("details");
-        } catch (error) {
-          console.error("Failed to sync license after billing return:", error);
+        // Retry up to 3 times with 2s backoff. The license may not be available
+        // immediately if the Stripe webhook hasn't finished processing yet
+        // (redirect and webhook fire nearly simultaneously).
+        let lastError: Error | null = null;
+        for (let attempt = 0; attempt < 3; attempt++) {
+          if (cancelled) return;
+          try {
+            // After checkout, exchange session_id for license; after portal, re-sync license
+            await claimLicense(sessionId ?? undefined);
+            if (cancelled) return;
+            refreshLicense();
+            // Refresh the page to update settings (including ee_features_enabled)
+            router.refresh();
+            // Navigate to billing details now that the license is active
+            changeView("details");
+            lastError = null;
+            break;
+          } catch (err) {
+            lastError = err instanceof Error ? err : new Error("Unknown error");
+            if (attempt < 2) {
+              await new Promise((resolve) => setTimeout(resolve, 2000));
+            }
+          }
+        }
+        if (cancelled) return;
+        if (lastError) {
+          console.error(
+            "Failed to sync license after billing return:",
+            lastError
+          );
+          // Show an activating banner on the plans view and keep retrying in the background.
+          sessionStorage.setItem(
+            BILLING_ACTIVATING_KEY,
+            String(Date.now() + 120_000)
+          );
+          setIsActivating(true);
+          changeView("plans");
         }
       }
-      refreshBilling();
+      if (!cancelled) refreshBilling();
     };
     handleBillingReturn();
-  }, [searchParams, router, refreshBilling, refreshLicense]);
+
+    return () => {
+      cancelled = true;
+    };
+    // changeView intentionally omitted: it only calls stable state setters and the
+    // effect runs at most once (when session_id/portal_return params are present).
+  }, [searchParams, router, refreshBilling, refreshLicense]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Poll every 15s while activating, up to 2 minutes, to detect when the license arrives.
+  useEffect(() => {
+    if (!isActivating) return;
+
+    let requestInFlight = false;
+
+    const intervalId = setInterval(async () => {
+      if (requestInFlight) return;
+      const raw = sessionStorage.getItem(BILLING_ACTIVATING_KEY);
+      if (!raw || Number(raw) <= Date.now()) {
+        // Expired — stop immediately without waiting for React cleanup
+        clearInterval(intervalId);
+        sessionStorage.removeItem(BILLING_ACTIVATING_KEY);
+        setIsActivating(false);
+        return;
+      }
+      requestInFlight = true;
+      try {
+        await claimLicense(undefined);
+        sessionStorage.removeItem(BILLING_ACTIVATING_KEY);
+        setIsActivating(false);
+        refreshLicense();
+        refreshBilling();
+        router.refresh();
+        changeView("details");
+      } catch (err) {
+        // License not ready yet — keep polling. Log so unexpected failures
+        // (network errors, 500s) are distinguishable from expected 404s.
+        console.debug("License activation poll: will retry", err);
+      } finally {
+        requestInFlight = false;
+      }
+    }, 15_000);
+
+    return () => clearInterval(intervalId);
+  }, [isActivating]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const handleRefresh = async () => {
     await Promise.all([
@@ -386,6 +474,22 @@ export default function BillingPage() {
       />
       <SettingsLayouts.Body>
         <div className="flex flex-col items-center gap-6">
+          {isActivating && (
+            <Message
+              static
+              warning
+              large
+              text="Your license is still activating"
+              description="Your license is being processed. You'll be taken to billing details automatically once confirmed."
+              icon
+              close
+              onClose={() => {
+                sessionStorage.removeItem(BILLING_ACTIVATING_KEY);
+                setIsActivating(false);
+              }}
+              className="w-full"
+            />
+          )}
           {renderContent()}
           {renderFooter()}
         </div>

web/src/app/admin/configuration/image-generation/ImageGenerationContent.tsx

@@ -1,11 +1,12 @@
 "use client";
 
-import { useState, useMemo } from "react";
+import { useState, useMemo, useEffect } from "react";
 import useSWR from "swr";
 import Text from "@/refresh-components/texts/Text";
 import { Select } from "@/refresh-components/cards";
 import { useCreateModal } from "@/refresh-components/contexts/ModalContext";
 import { toast } from "@/hooks/useToast";
+import { Section } from "@/layouts/general-layouts";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { LLMProviderResponse, LLMProviderView } from "@/interfaces/llm";
 import {
@@ -17,9 +18,16 @@ import {
   ImageGenerationConfigView,
   setDefaultImageGenerationConfig,
   unsetDefaultImageGenerationConfig,
+  deleteImageGenerationConfig,
 } from "@/lib/configuration/imageConfigurationService";
 import { ProviderIcon } from "@/app/admin/configuration/llm/ProviderIcon";
 import Message from "@/refresh-components/messages/Message";
+import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
+import { Button } from "@opal/components";
+import { SvgSlash, SvgUnplug } from "@opal/icons";
+
+const NO_DEFAULT_VALUE = "__none__";
 
 export default function ImageGenerationContent() {
   const {
@@ -47,6 +55,11 @@ export default function ImageGenerationContent() {
   );
   const [editConfig, setEditConfig] =
     useState<ImageGenerationConfigView | null>(null);
+  const [disconnectProvider, setDisconnectProvider] =
+    useState<ImageProvider | null>(null);
+  const [replacementProviderId, setReplacementProviderId] = useState<
+    string | null
+  >(null);
 
   const connectedProviderIds = useMemo(() => {
     return new Set(configs.map((c) => c.image_provider_id));
@@ -115,6 +128,29 @@ export default function ImageGenerationContent() {
     modal.toggle(true);
   };
 
+  const handleDisconnect = async () => {
+    if (!disconnectProvider) return;
+    try {
+      // If a replacement was selected (not "No Default"), activate it first
+      if (replacementProviderId && replacementProviderId !== NO_DEFAULT_VALUE) {
+        await setDefaultImageGenerationConfig(replacementProviderId);
+      }
+
+      await deleteImageGenerationConfig(disconnectProvider.image_provider_id);
+      toast.success(`${disconnectProvider.title} disconnected`);
+      refetchConfigs();
+      refetchProviders();
+    } catch (error) {
+      console.error("Failed to disconnect image generation provider:", error);
+      toast.error(
+        error instanceof Error ? error.message : "Failed to disconnect"
+      );
+    } finally {
+      setDisconnectProvider(null);
+      setReplacementProviderId(null);
+    }
+  };
+
   const handleModalSuccess = () => {
     toast.success("Provider configured successfully");
     setEditConfig(null);
@@ -130,6 +166,36 @@ export default function ImageGenerationContent() {
     );
   }
 
+  // Compute replacement options when disconnecting an active provider
+  const isDisconnectingDefault =
+    disconnectProvider &&
+    defaultConfig?.image_provider_id === disconnectProvider.image_provider_id;
+
+  // Group connected replacement models by provider (excluding the model being disconnected)
+  const replacementGroups = useMemo(() => {
+    if (!disconnectProvider) return [];
+    return IMAGE_PROVIDER_GROUPS.map((group) => ({
+      ...group,
+      providers: group.providers.filter(
+        (p) =>
+          p.image_provider_id !== disconnectProvider.image_provider_id &&
+          connectedProviderIds.has(p.image_provider_id)
+      ),
+    })).filter((g) => g.providers.length > 0);
+  }, [disconnectProvider, connectedProviderIds]);
+
+  const needsReplacement = !!isDisconnectingDefault;
+  const hasReplacements = replacementGroups.length > 0;
+
+  // Auto-select first replacement when modal opens
+  useEffect(() => {
+    if (needsReplacement && !replacementProviderId && hasReplacements) {
+      const firstGroup = replacementGroups[0];
+      const firstModel = firstGroup?.providers[0];
+      if (firstModel) setReplacementProviderId(firstModel.image_provider_id);
+    }
+  }, [disconnectProvider]); // eslint-disable-line react-hooks/exhaustive-deps
+
   return (
     <>
       <div className="flex flex-col gap-6">
@@ -175,6 +241,11 @@ export default function ImageGenerationContent() {
                   onSelect={() => handleSelect(provider)}
                   onDeselect={() => handleDeselect(provider)}
                   onEdit={() => handleEdit(provider)}
+                  onDisconnect={
+                    getStatus(provider) !== "disconnected"
+                      ? () => setDisconnectProvider(provider)
+                      : undefined
+                  }
                 />
               ))}
             </div>
@@ -182,6 +253,105 @@ export default function ImageGenerationContent() {
         ))}
       </div>
 
+      {disconnectProvider && (
+        <ConfirmationModalLayout
+          icon={SvgUnplug}
+          title={`Disconnect ${disconnectProvider.title}`}
+          description="This will remove the stored credentials for this provider."
+          onClose={() => {
+            setDisconnectProvider(null);
+            setReplacementProviderId(null);
+          }}
+          submit={
+            <Button
+              variant="danger"
+              onClick={() => void handleDisconnect()}
+              disabled={
+                needsReplacement && hasReplacements && !replacementProviderId
+              }
+            >
+              Disconnect
+            </Button>
+          }
+        >
+          {needsReplacement ? (
+            hasReplacements ? (
+              <Section alignItems="start">
+                <Text as="p" text03>
+                  <b>{disconnectProvider.title}</b> is currently the default
+                  image generation model. Session history will be preserved.
+                </Text>
+                <Section alignItems="start" gap={0.25}>
+                  <Text as="p" text04>
+                    Set New Default
+                  </Text>
+                  <InputSelect
+                    value={replacementProviderId ?? undefined}
+                    onValueChange={(v) => setReplacementProviderId(v)}
+                  >
+                    <InputSelect.Trigger placeholder="Select a replacement model" />
+                    <InputSelect.Content>
+                      {replacementGroups.map((group) => (
+                        <InputSelect.Group key={group.name}>
+                          <InputSelect.Label>{group.name}</InputSelect.Label>
+                          {group.providers.map((p) => (
+                            <InputSelect.Item
+                              key={p.image_provider_id}
+                              value={p.image_provider_id}
+                              icon={() => (
+                                <ProviderIcon
+                                  provider={p.provider_name}
+                                  size={16}
+                                />
+                              )}
+                            >
+                              {p.title}
+                            </InputSelect.Item>
+                          ))}
+                        </InputSelect.Group>
+                      ))}
+                      <InputSelect.Separator />
+                      <InputSelect.Item
+                        value={NO_DEFAULT_VALUE}
+                        icon={SvgSlash}
+                      >
+                        <span>
+                          <b>No Default</b>
+                          <span className="text-text-03">
+                            {" "}
+                            (Disable Image Generation)
+                          </span>
+                        </span>
+                      </InputSelect.Item>
+                    </InputSelect.Content>
+                  </InputSelect>
+                </Section>
+              </Section>
+            ) : (
+              <>
+                <Text as="p" text03>
+                  <b>{disconnectProvider.title}</b> is currently the default
+                  image generation model.
+                </Text>
+                <Text as="p" text03>
+                  Connect another provider to continue using image generation.
+                </Text>
+              </>
+            )
+          ) : (
+            <>
+              <Text as="p" text03>
+                <b>{disconnectProvider.title}</b> models will no longer be used
+                to generate images.
+              </Text>
+              <Text as="p" text03>
+                Session history will be preserved.
+              </Text>
+            </>
+          )}
+        </ConfirmationModalLayout>
+      )}
+
       {activeProvider && (
         <modal.Provider>
           <ImageGenerationConnectionModal

web/src/app/admin/configuration/llm/utils.ts

@@ -23,6 +23,7 @@ import {
   BedrockModelResponse,
   LMStudioModelResponse,
   LiteLLMProxyModelResponse,
+  BifrostModelResponse,
   ModelConfiguration,
   LLMProviderName,
   BedrockFetchParams,
@@ -30,8 +31,9 @@ import {
   LMStudioFetchParams,
   OpenRouterFetchParams,
   LiteLLMProxyFetchParams,
+  BifrostFetchParams,
 } from "@/interfaces/llm";
-import { SvgAws, SvgOpenrouter } from "@opal/icons";
+import { SvgAws, SvgBifrost, SvgOpenrouter } from "@opal/icons";
 
 // Aggregator providers that host models from multiple vendors
 export const AGGREGATOR_PROVIDERS = new Set([
@@ -41,6 +43,7 @@ export const AGGREGATOR_PROVIDERS = new Set([
   "ollama_chat",
   "lm_studio",
   "litellm_proxy",
+  "bifrost",
   "vertex_ai",
 ]);
 
@@ -78,6 +81,7 @@ export const getProviderIcon = (
     bedrock_converse: SvgAws,
     openrouter: SvgOpenrouter,
     litellm_proxy: LiteLLMIcon,
+    bifrost: SvgBifrost,
     vertex_ai: GeminiIcon,
   };
 
@@ -263,8 +267,11 @@ export const fetchOpenRouterModels = async (
       try {
         const errorData = await response.json();
         errorMessage = errorData.detail || errorData.message || errorMessage;
-      } catch {
-        // ignore JSON parsing errors
+      } catch (jsonError) {
+        console.warn(
+          "Failed to parse OpenRouter model fetch error response",
+          jsonError
+        );
       }
       return { models: [], error: errorMessage };
     }
@@ -319,8 +326,11 @@ export const fetchLMStudioModels = async (
       try {
         const errorData = await response.json();
         errorMessage = errorData.detail || errorData.message || errorMessage;
-      } catch {
-        // ignore JSON parsing errors
+      } catch (jsonError) {
+        console.warn(
+          "Failed to parse LM Studio model fetch error response",
+          jsonError
+        );
       }
       return { models: [], error: errorMessage };
     }
@@ -343,6 +353,64 @@ export const fetchLMStudioModels = async (
   }
 };
 
+/**
+ * Fetches Bifrost models directly without any form state dependencies.
+ * Uses snake_case params to match API structure.
+ */
+export const fetchBifrostModels = async (
+  params: BifrostFetchParams
+): Promise<{ models: ModelConfiguration[]; error?: string }> => {
+  const apiBase = params.api_base;
+  if (!apiBase) {
+    return { models: [], error: "API Base is required" };
+  }
+
+  try {
+    const response = await fetch("/api/admin/llm/bifrost/available-models", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        api_base: apiBase,
+        api_key: params.api_key,
+        provider_name: params.provider_name,
+      }),
+      signal: params.signal,
+    });
+
+    if (!response.ok) {
+      let errorMessage = "Failed to fetch models";
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.detail || errorData.message || errorMessage;
+      } catch (jsonError) {
+        console.warn(
+          "Failed to parse Bifrost model fetch error response",
+          jsonError
+        );
+      }
+      return { models: [], error: errorMessage };
+    }
+
+    const data: BifrostModelResponse[] = await response.json();
+    const models: ModelConfiguration[] = data.map((modelData) => ({
+      name: modelData.name,
+      display_name: modelData.display_name,
+      is_visible: true,
+      max_input_tokens: modelData.max_input_tokens,
+      supports_image_input: modelData.supports_image_input,
+      supports_reasoning: modelData.supports_reasoning,
+    }));
+
+    return { models };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    return { models: [], error: errorMessage };
+  }
+};
+
 /**
  * Fetches LiteLLM Proxy models directly without any form state dependencies.
  * Uses snake_case params to match API structure.
@@ -456,6 +524,13 @@ export const fetchModels = async (
         provider_name: formValues.name,
         signal,
       });
+    case LLMProviderName.BIFROST:
+      return fetchBifrostModels({
+        api_base: formValues.api_base,
+        api_key: formValues.api_key,
+        provider_name: formValues.name,
+        signal,
+      });
     default:
       return { models: [], error: `Unknown provider: ${providerName}` };
   }
@@ -469,6 +544,7 @@ export function canProviderFetchModels(providerName?: string) {
     case LLMProviderName.LM_STUDIO:
     case LLMProviderName.OPENROUTER:
     case LLMProviderName.LITELLM_PROXY:
+    case LLMProviderName.BIFROST:
       return true;
     default:
       return false;

web/src/app/admin/configuration/search/UpgradingPage.tsx

@@ -7,7 +7,9 @@ import {
   FailedConnectorIndexingStatus,
   ValidStatuses,
 } from "@/lib/types";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Title from "@/components/ui/title";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
@@ -199,45 +201,30 @@ export default function UpgradingPage({
                     />
                   )}
 
-                  <Text className="my-4">
-                    {futureEmbeddingModel.switchover_type === "active_only" ? (
-                      <>
-                        The table below shows the re-indexing progress of active
-                        (non-paused) connectors. Once all active connectors have
-                        been re-indexed successfully, the new model will be used
-                        for all search queries. Paused connectors will continue
-                        to be indexed in the background but won&apos;t block the
-                        switchover. Until then, we will use the old model so
-                        that no downtime is necessary during this transition.
-                        <br />
-                        Note: User file re-indexing progress is not shown. You
-                        will see this page until all active connectors are
-                        re-indexed!
-                      </>
-                    ) : (
-                      <>
-                        The table below shows the re-indexing progress of all
-                        existing connectors. Once all connectors have been
-                        re-indexed successfully, the new model will be used for
-                        all search queries. Until then, we will use the old
-                        model so that no downtime is necessary during this
-                        transition.
-                        <br />
-                        Note: User file re-indexing progress is not shown. You
-                        will see this page until all user files are re-indexed!
-                      </>
-                    )}
+                  <Spacer rem={1} />
+                  <Text as="p">
+                    {futureEmbeddingModel.switchover_type === "active_only"
+                      ? markdown(
+                          "The table below shows the re-indexing progress of active (non-paused) connectors. Once all active connectors have been re-indexed successfully, the new model will be used for all search queries. Paused connectors will continue to be indexed in the background but won't block the switchover. Until then, we will use the old model so that no downtime is necessary during this transition.\nNote: User file re-indexing progress is not shown. You will see this page until all active connectors are re-indexed!"
+                        )
+                      : markdown(
+                          "The table below shows the re-indexing progress of all existing connectors. Once all connectors have been re-indexed successfully, the new model will be used for all search queries. Until then, we will use the old model so that no downtime is necessary during this transition.\nNote: User file re-indexing progress is not shown. You will see this page until all user files are re-indexed!"
+                        )}
                   </Text>
+                  <Spacer rem={1} />
 
                   {sortedReindexingProgress ? (
                     <>
                       {futureEmbeddingModel.switchover_type === "active_only" &&
                         !hasVisibleReindexingProgress && (
-                          <Text className="text-text-700 mt-4">
-                            All connectors are currently paused, so none are
-                            blocking the switchover. Paused connectors will keep
-                            re-indexing in the background.
-                          </Text>
+                          <>
+                            <Spacer rem={1} />
+                            <Text as="p">
+                              All connectors are currently paused, so none are
+                              blocking the switchover. Paused connectors will
+                              keep re-indexing in the background.
+                            </Text>
+                          </>
                         )}
                       {hasVisibleReindexingProgress && (
                         <ReindexingProgressTable

web/src/app/admin/configuration/search/page.tsx

@@ -3,7 +3,7 @@
 import { ThreeDotsLoader } from "@/components/Loading";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 import { Button } from "@opal/components";
 import useSWR from "swr";
@@ -107,8 +107,10 @@ function Main() {
                 <div className="px-1 w-full rounded-lg">
                   <div className="space-y-4">
                     <div>
-                      <Text className="font-semibold">Multipass Indexing</Text>
-                      <Text className="text-text-700">
+                      <Text as="p" font="main-ui-action">
+                        Multipass Indexing
+                      </Text>
+                      <Text as="p">
                         {searchSettings.multipass_indexing
                           ? "Enabled"
                           : "Disabled"}
@@ -116,8 +118,10 @@ function Main() {
                     </div>
 
                     <div>
-                      <Text className="font-semibold">Contextual RAG</Text>
-                      <Text className="text-text-700">
+                      <Text as="p" font="main-ui-action">
+                        Contextual RAG
+                      </Text>
+                      <Text as="p">
                         {searchSettings.enable_contextual_rag
                           ? "Enabled"
                           : "Disabled"}

web/src/app/admin/configuration/voice/VoiceProviderSetupModal.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { markdown } from "@opal/utils";
 import Image from "next/image";
 import { FunctionComponent, useState, useEffect } from "react";
 import {
@@ -436,22 +437,9 @@ export default function VoiceProviderSetupModal({
             {providerType === "azure" && (
               <Vertical
                 title="Target URI"
-                subDescription={
-                  <>
-                    Paste the endpoint shown in{" "}
-                    <a
-                      href="https://portal.azure.com/"
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      className="underline"
-                    >
-                      Azure Portal (Keys and Endpoint)
-                    </a>
-                    . Onyx extracts the speech region from this URL. Examples:
-                    https://westus.api.cognitive.microsoft.com/ or
-                    https://westus.tts.speech.microsoft.com/.
-                  </>
-                }
+                subDescription={markdown(
+                  "Paste the endpoint shown in [Azure Portal (Keys and Endpoint)](https://portal.azure.com/). Onyx extracts the speech region from this URL. Examples: https://westus.api.cognitive.microsoft.com/ or https://westus.tts.speech.microsoft.com/."
+                )}
                 nonInteractive
               >
                 <InputTypeIn
@@ -503,24 +491,14 @@ export default function VoiceProviderSetupModal({
             {mode === "tts" && (
               <Vertical
                 title="Voice"
-                subDescription={
-                  <>
-                    This voice will be used for spoken responses. See full list
-                    of supported languages and voices at{" "}
-                    <a
-                      href={
-                        PROVIDER_VOICE_DOCS_URLS[providerType]?.url ??
-                        PROVIDER_DOCS_URLS[providerType]
-                      }
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      className="underline"
-                    >
-                      {PROVIDER_VOICE_DOCS_URLS[providerType]?.label ?? label}
-                    </a>
-                    .
-                  </>
-                }
+                subDescription={markdown(
+                  `This voice will be used for spoken responses. See full list of supported languages and voices at [${
+                    PROVIDER_VOICE_DOCS_URLS[providerType]?.label ?? label
+                  }](${
+                    PROVIDER_VOICE_DOCS_URLS[providerType]?.url ??
+                    PROVIDER_DOCS_URLS[providerType]
+                  }).`
+                )}
                 nonInteractive
               >
                 <InputComboBox

web/src/app/admin/configuration/web-search/page.tsx

@@ -1,32 +1,25 @@
 "use client";
 
 import Image from "next/image";
-import { useMemo, useState, useReducer } from "react";
+import { useEffect, useMemo, useState, useReducer } from "react";
 import { InfoIcon } from "@/components/icons/icons";
 import Text from "@/refresh-components/texts/Text";
+import { Select } from "@/refresh-components/cards";
+import { Section } from "@/layouts/general-layouts";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { Content } from "@opal/layouts";
 import useSWR from "swr";
 import { errorHandlingFetcher, FetchError } from "@/lib/fetcher";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { Callout } from "@/components/ui/callout";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
-import { Disabled } from "@opal/core";
 import { cn } from "@/lib/utils";
-import {
-  SvgArrowExchange,
-  SvgArrowRightCircle,
-  SvgCheckSquare,
-  SvgEdit,
-  SvgGlobe,
-  SvgOnyxLogo,
-  SvgX,
-} from "@opal/icons";
+import { toast } from "@/hooks/useToast";
+import { SvgGlobe, SvgOnyxLogo, SvgSlash, SvgUnplug } from "@opal/icons";
+import { Button as OpalButton } from "@opal/components";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 import { WebProviderSetupModal } from "@/app/admin/configuration/web-search/WebProviderSetupModal";
-
-const route = ADMIN_ROUTES.WEB_SEARCH;
+import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
 import {
   SEARCH_PROVIDERS_URL,
   SEARCH_PROVIDER_DETAILS,
@@ -58,6 +51,10 @@ import {
 } from "@/app/admin/configuration/web-search/WebProviderModalReducer";
 import { connectProviderFlow } from "@/app/admin/configuration/web-search/connectProviderFlow";
 
+const NO_DEFAULT_VALUE = "__none__";
+
+const route = ADMIN_ROUTES.WEB_SEARCH;
+
 interface WebSearchProviderView {
   id: number;
   name: string;
@@ -76,27 +73,151 @@ interface WebContentProviderView {
   has_api_key: boolean;
 }
 
-interface HoverIconButtonProps extends React.ComponentProps<typeof Button> {
-  isHovered: boolean;
-  onMouseEnter: () => void;
-  onMouseLeave: () => void;
-  children: React.ReactNode;
+interface DisconnectTargetState {
+  id: number;
+  label: string;
+  category: "search" | "content";
+  providerType: string;
 }
 
-function HoverIconButton({
-  isHovered,
-  onMouseEnter,
-  onMouseLeave,
-  children,
-  ...buttonProps
-}: HoverIconButtonProps) {
+function WebSearchDisconnectModal({
+  disconnectTarget,
+  searchProviders,
+  contentProviders,
+  replacementProviderId,
+  onReplacementChange,
+  onClose,
+  onDisconnect,
+}: {
+  disconnectTarget: DisconnectTargetState;
+  searchProviders: WebSearchProviderView[];
+  contentProviders: WebContentProviderView[];
+  replacementProviderId: string | null;
+  onReplacementChange: (id: string | null) => void;
+  onClose: () => void;
+  onDisconnect: () => void;
+}) {
+  const isSearch = disconnectTarget.category === "search";
+
+  // Determine if the target is currently the active/selected provider
+  const isActive = isSearch
+    ? searchProviders.find((p) => p.id === disconnectTarget.id)?.is_active ??
+      false
+    : contentProviders.find((p) => p.id === disconnectTarget.id)?.is_active ??
+      false;
+
+  // Find other configured providers as replacements
+  const replacementOptions = isSearch
+    ? searchProviders.filter(
+        (p) => p.id !== disconnectTarget.id && p.id > 0 && p.has_api_key
+      )
+    : contentProviders.filter(
+        (p) =>
+          p.id !== disconnectTarget.id &&
+          p.provider_type !== "onyx_web_crawler" &&
+          p.id > 0 &&
+          p.has_api_key
+      );
+
+  const needsReplacement = isActive;
+  const hasReplacements = replacementOptions.length > 0;
+
+  const getLabel = (p: { name: string; provider_type: string }) => {
+    if (isSearch) {
+      const details =
+        SEARCH_PROVIDER_DETAILS[p.provider_type as WebSearchProviderType];
+      return details?.label ?? p.name ?? p.provider_type;
+    }
+    const details = CONTENT_PROVIDER_DETAILS[p.provider_type];
+    return details?.label ?? p.name ?? p.provider_type;
+  };
+
+  const categoryLabel = isSearch ? "search engine" : "web crawler";
+  const featureLabel = isSearch ? "web search" : "web crawling";
+  const disableLabel = isSearch ? "Disable Web Search" : "Disable Web Crawling";
+
+  // Auto-select first replacement when modal opens
+  useEffect(() => {
+    if (needsReplacement && hasReplacements && !replacementProviderId) {
+      const first = replacementOptions[0];
+      if (first) onReplacementChange(String(first.id));
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
   return (
-    <div onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
-      {/* TODO(@raunakab): migrate to opal Button once HoverIconButtonProps typing is resolved */}
-      <Button {...buttonProps} rightIcon={isHovered ? SvgX : SvgCheckSquare}>
-        {children}
-      </Button>
-    </div>
+    <ConfirmationModalLayout
+      icon={SvgUnplug}
+      title={`Disconnect ${disconnectTarget.label}`}
+      description="This will remove the stored credentials for this provider."
+      onClose={onClose}
+      submit={
+        <OpalButton
+          variant="danger"
+          onClick={onDisconnect}
+          disabled={
+            needsReplacement && hasReplacements && !replacementProviderId
+          }
+        >
+          Disconnect
+        </OpalButton>
+      }
+    >
+      {needsReplacement ? (
+        hasReplacements ? (
+          <Section alignItems="start">
+            <Text as="p" text03>
+              <b>{disconnectTarget.label}</b> is currently the active{" "}
+              {categoryLabel}. Search history will be preserved.
+            </Text>
+            <Section alignItems="start" gap={0.25}>
+              <Text as="p" secondaryBody text03>
+                Set New Default
+              </Text>
+              <InputSelect
+                value={replacementProviderId ?? undefined}
+                onValueChange={(v) => onReplacementChange(v)}
+              >
+                <InputSelect.Trigger placeholder="Select a replacement provider" />
+                <InputSelect.Content>
+                  {replacementOptions.map((p) => (
+                    <InputSelect.Item key={p.id} value={String(p.id)}>
+                      {getLabel(p)}
+                    </InputSelect.Item>
+                  ))}
+                  <InputSelect.Separator />
+                  <InputSelect.Item value={NO_DEFAULT_VALUE} icon={SvgSlash}>
+                    <span>
+                      <b>No Default</b>
+                      <span className="text-text-03"> ({disableLabel})</span>
+                    </span>
+                  </InputSelect.Item>
+                </InputSelect.Content>
+              </InputSelect>
+            </Section>
+          </Section>
+        ) : (
+          <>
+            <Text as="p" text03>
+              <b>{disconnectTarget.label}</b> is currently the active{" "}
+              {categoryLabel}.
+            </Text>
+            <Text as="p" text03>
+              Connect another provider to continue using {featureLabel}.
+            </Text>
+          </>
+        )
+      ) : (
+        <>
+          <Text as="p" text03>
+            {isSearch ? "Web search" : "Web crawling"} will no longer be routed
+            through <b>{disconnectTarget.label}</b>.
+          </Text>
+          <Text as="p" text03>
+            Search history will be preserved.
+          </Text>
+        </>
+      )}
+    </ConfirmationModalLayout>
   );
 }
 
@@ -105,6 +226,11 @@ export default function Page() {
     WebProviderModalReducer,
     initialWebProviderModalState
   );
+  const [disconnectTarget, setDisconnectTarget] =
+    useState<DisconnectTargetState | null>(null);
+  const [replacementProviderId, setReplacementProviderId] = useState<
+    string | null
+  >(null);
   const [contentModal, dispatchContentModal] = useReducer(
     WebProviderModalReducer,
     initialWebProviderModalState
@@ -113,8 +239,6 @@ export default function Page() {
   const [contentActivationError, setContentActivationError] = useState<
     string | null
   >(null);
-  const [hoveredButtonKey, setHoveredButtonKey] = useState<string | null>(null);
-
   const {
     data: searchProvidersData,
     error: searchProvidersError,
@@ -833,6 +957,67 @@ export default function Page() {
     });
   };
 
+  const handleDisconnectProvider = async () => {
+    if (!disconnectTarget) return;
+    const { id, category } = disconnectTarget;
+
+    try {
+      // If a replacement was selected (not "No Default"), activate it first
+      if (replacementProviderId && replacementProviderId !== NO_DEFAULT_VALUE) {
+        const repId = Number(replacementProviderId);
+        const activateEndpoint =
+          category === "search"
+            ? `/api/admin/web-search/search-providers/${repId}/activate`
+            : `/api/admin/web-search/content-providers/${repId}/activate`;
+        const activateResp = await fetch(activateEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+        });
+        if (!activateResp.ok) {
+          const errorBody = await activateResp.json().catch(() => ({}));
+          throw new Error(
+            typeof errorBody?.detail === "string"
+              ? errorBody.detail
+              : "Failed to activate replacement provider."
+          );
+        }
+      }
+
+      const response = await fetch(
+        `/api/admin/web-search/${category}-providers/${id}`,
+        { method: "DELETE" }
+      );
+
+      if (!response.ok) {
+        const errorBody = await response.json().catch((parseErr) => {
+          console.error("Failed to parse disconnect error response:", parseErr);
+          return {};
+        });
+        throw new Error(
+          typeof errorBody?.detail === "string"
+            ? errorBody.detail
+            : "Failed to disconnect provider."
+        );
+      }
+
+      toast.success(`${disconnectTarget.label} disconnected`);
+      await mutateSearchProviders();
+      await mutateContentProviders();
+    } catch (error) {
+      console.error("Failed to disconnect web search provider:", error);
+      const message =
+        error instanceof Error ? error.message : "Unexpected error occurred.";
+      if (category === "search") {
+        setActivationError(message);
+      } else {
+        setContentActivationError(message);
+      }
+    } finally {
+      setDisconnectTarget(null);
+      setReplacementProviderId(null);
+    }
+  };
+
   return (
     <>
       <SettingsLayouts.Root>
@@ -894,149 +1079,79 @@ export default function Page() {
                     provider
                   );
                   const isActive = provider?.is_active ?? false;
-                  const isHighlighted = isActive;
                   const providerId = provider?.id;
                   const canOpenModal =
                     isBuiltInSearchProviderType(providerType);
 
-                  const buttonState = (() => {
-                    if (!provider || !isConfigured) {
-                      return {
-                        label: "Connect",
-                        disabled: false,
-                        icon: "arrow" as const,
-                        onClick: canOpenModal
+                  const status: "disconnected" | "connected" | "selected" =
+                    !isConfigured
+                      ? "disconnected"
+                      : isActive
+                        ? "selected"
+                        : "connected";
+
+                  return (
+                    <Select
+                      key={`${key}-${providerType}`}
+                      icon={() =>
+                        logoSrc ? (
+                          <Image
+                            src={logoSrc}
+                            alt={`${label} logo`}
+                            width={16}
+                            height={16}
+                          />
+                        ) : (
+                          <SvgGlobe size={16} />
+                        )
+                      }
+                      title={label}
+                      description={subtitle}
+                      status={status}
+                      onConnect={
+                        canOpenModal
                           ? () => {
                               openSearchModal(providerType, provider);
                               setActivationError(null);
                             }
-                          : undefined,
-                      };
-                    }
-
-                    if (isActive) {
-                      return {
-                        label: "Current Default",
-                        disabled: false,
-                        icon: "check" as const,
-                        onClick: providerId
+                          : undefined
+                      }
+                      onSelect={
+                        providerId
+                          ? () => {
+                              void handleActivateSearchProvider(providerId);
+                            }
+                          : undefined
+                      }
+                      onDeselect={
+                        providerId
                           ? () => {
                               void handleDeactivateSearchProvider(providerId);
                             }
-                          : undefined,
-                      };
-                    }
-
-                    return {
-                      label: "Set as Default",
-                      disabled: false,
-                      icon: "arrow-circle" as const,
-                      onClick: providerId
-                        ? () => {
-                            void handleActivateSearchProvider(providerId);
-                          }
-                        : undefined,
-                    };
-                  })();
-
-                  const buttonKey = `search-${key}-${providerType}`;
-                  const isButtonHovered = hoveredButtonKey === buttonKey;
-                  const isCardClickable =
-                    buttonState.icon === "arrow" &&
-                    typeof buttonState.onClick === "function" &&
-                    !buttonState.disabled;
-
-                  const handleCardClick = () => {
-                    if (isCardClickable) {
-                      buttonState.onClick?.();
-                    }
-                  };
-
-                  return (
-                    <div
-                      key={`${key}-${providerType}`}
-                      onClick={isCardClickable ? handleCardClick : undefined}
-                      className={cn(
-                        "flex items-start justify-between gap-3 rounded-16 border p-1 bg-background-neutral-00",
-                        isHighlighted
-                          ? "border-action-link-05"
-                          : "border-border-01",
-                        isCardClickable &&
-                          "cursor-pointer hover:bg-background-tint-01 transition-colors"
-                      )}
-                    >
-                      <div className="flex flex-1 items-start gap-1 px-2 py-1">
-                        {renderLogo({
-                          logoSrc,
-                          alt: `${label} logo`,
-                          size: 16,
-                          isHighlighted,
-                        })}
-                        <Content
-                          title={label}
-                          description={subtitle}
-                          sizePreset="main-ui"
-                          variant="section"
-                        />
-                      </div>
-                      <div className="flex items-center justify-end gap-2">
-                        {isConfigured && (
-                          <OpalButton
-                            icon={SvgEdit}
-                            tooltip="Edit"
-                            prominence="tertiary"
-                            size="sm"
-                            onClick={() => {
-                              if (!canOpenModal) return;
+                          : undefined
+                      }
+                      onEdit={
+                        isConfigured && canOpenModal
+                          ? () => {
                               openSearchModal(
                                 providerType as WebSearchProviderType,
                                 provider
                               );
-                            }}
-                            aria-label={`Edit ${label}`}
-                          />
-                        )}
-                        {buttonState.icon === "check" ? (
-                          <HoverIconButton
-                            isHovered={isButtonHovered}
-                            onMouseEnter={() => setHoveredButtonKey(buttonKey)}
-                            onMouseLeave={() => setHoveredButtonKey(null)}
-                            action={true}
-                            tertiary
-                            disabled={buttonState.disabled}
-                            onClick={(e) => {
-                              e.stopPropagation();
-                              buttonState.onClick?.();
-                            }}
-                          >
-                            {buttonState.label}
-                          </HoverIconButton>
-                        ) : (
-                          <Disabled
-                            disabled={
-                              buttonState.disabled || !buttonState.onClick
                             }
-                          >
-                            <OpalButton
-                              prominence="tertiary"
-                              onClick={(e) => {
-                                e.stopPropagation();
-                                buttonState.onClick?.();
-                              }}
-                              rightIcon={
-                                buttonState.icon === "arrow"
-                                  ? SvgArrowExchange
-                                  : buttonState.icon === "arrow-circle"
-                                    ? SvgArrowRightCircle
-                                    : undefined
-                              }
-                            >
-                              {buttonState.label}
-                            </OpalButton>
-                          </Disabled>
-                        )}
-                      </div>
-                    </div>
+                          : undefined
+                      }
+                      onDisconnect={
+                        isConfigured && provider && provider.id > 0
+                          ? () =>
+                              setDisconnectTarget({
+                                id: provider.id,
+                                label,
+                                category: "search",
+                                providerType,
+                              })
+                          : undefined
+                      }
+                    />
                   );
                 }
               )}
@@ -1076,161 +1191,81 @@ export default function Page() {
                 const isCurrentCrawler =
                   provider.provider_type === currentContentProviderType;
 
-                const buttonState = (() => {
-                  if (!isConfigured) {
-                    return {
-                      label: "Connect",
-                      icon: "arrow" as const,
-                      disabled: false,
-                      onClick: () => {
-                        openContentModal(provider.provider_type, provider);
-                        setContentActivationError(null);
-                      },
-                    };
-                  }
+                const status: "disconnected" | "connected" | "selected" =
+                  !isConfigured
+                    ? "disconnected"
+                    : isCurrentCrawler
+                      ? "selected"
+                      : "connected";
 
-                  if (isCurrentCrawler) {
-                    return {
-                      label: "Current Crawler",
-                      icon: "check" as const,
-                      disabled: false,
-                      onClick: () => {
-                        void handleDeactivateContentProvider(
-                          providerId,
-                          provider.provider_type
-                        );
-                      },
-                    };
-                  }
+                const canActivate =
+                  providerId > 0 ||
+                  provider.provider_type === "onyx_web_crawler" ||
+                  isConfigured;
 
-                  const canActivate =
-                    providerId > 0 ||
-                    provider.provider_type === "onyx_web_crawler" ||
-                    isConfigured;
-
-                  return {
-                    label: "Set as Default",
-                    icon: "arrow-circle" as const,
-                    disabled: !canActivate,
-                    onClick: canActivate
-                      ? () => {
-                          void handleActivateContentProvider(provider);
-                        }
-                      : undefined,
-                  };
-                })();
-
-                const contentButtonKey = `content-${provider.provider_type}-${provider.id}`;
-                const isContentButtonHovered =
-                  hoveredButtonKey === contentButtonKey;
-                const isContentCardClickable =
-                  buttonState.icon === "arrow" &&
-                  typeof buttonState.onClick === "function" &&
-                  !buttonState.disabled;
-
-                const handleContentCardClick = () => {
-                  if (isContentCardClickable) {
-                    buttonState.onClick?.();
-                  }
-                };
+                const contentLogoSrc =
+                  CONTENT_PROVIDER_DETAILS[provider.provider_type]?.logoSrc;
 
                 return (
-                  <div
+                  <Select
                     key={`${provider.provider_type}-${provider.id}`}
-                    onClick={
-                      isContentCardClickable
-                        ? handleContentCardClick
+                    icon={() =>
+                      contentLogoSrc ? (
+                        <Image
+                          src={contentLogoSrc}
+                          alt={`${label} logo`}
+                          width={16}
+                          height={16}
+                        />
+                      ) : provider.provider_type === "onyx_web_crawler" ? (
+                        <SvgOnyxLogo size={16} />
+                      ) : (
+                        <SvgGlobe size={16} />
+                      )
+                    }
+                    title={label}
+                    description={subtitle}
+                    status={status}
+                    selectedLabel="Current Crawler"
+                    onConnect={() => {
+                      openContentModal(provider.provider_type, provider);
+                      setContentActivationError(null);
+                    }}
+                    onSelect={
+                      canActivate
+                        ? () => {
+                            void handleActivateContentProvider(provider);
+                          }
                         : undefined
                     }
-                    className={cn(
-                      "flex items-start justify-between gap-3 rounded-16 border p-1 bg-background-neutral-00",
-                      isCurrentCrawler
-                        ? "border-action-link-05"
-                        : "border-border-01",
-                      isContentCardClickable &&
-                        "cursor-pointer hover:bg-background-tint-01 transition-colors"
-                    )}
-                  >
-                    <div className="flex flex-1 items-start gap-1 px-2 py-1">
-                      {renderLogo({
-                        logoSrc:
-                          CONTENT_PROVIDER_DETAILS[provider.provider_type]
-                            ?.logoSrc,
-                        alt: `${label} logo`,
-                        fallback:
-                          provider.provider_type === "onyx_web_crawler" ? (
-                            <SvgOnyxLogo size={16} />
-                          ) : undefined,
-                        size: 16,
-                        isHighlighted: isCurrentCrawler,
-                      })}
-                      <Content
-                        title={label}
-                        description={subtitle}
-                        sizePreset="main-ui"
-                        variant="section"
-                      />
-                    </div>
-                    <div className="flex items-center justify-end gap-2">
-                      {provider.provider_type !== "onyx_web_crawler" &&
-                        isConfigured && (
-                          <OpalButton
-                            icon={SvgEdit}
-                            tooltip="Edit"
-                            prominence="tertiary"
-                            size="sm"
-                            onClick={() => {
-                              openContentModal(
-                                provider.provider_type,
-                                provider
-                              );
-                            }}
-                            aria-label={`Edit ${label}`}
-                          />
-                        )}
-                      {buttonState.icon === "check" ? (
-                        <HoverIconButton
-                          isHovered={isContentButtonHovered}
-                          onMouseEnter={() =>
-                            setHoveredButtonKey(contentButtonKey)
+                    onDeselect={() => {
+                      void handleDeactivateContentProvider(
+                        providerId,
+                        provider.provider_type
+                      );
+                    }}
+                    onEdit={
+                      provider.provider_type !== "onyx_web_crawler" &&
+                      isConfigured
+                        ? () => {
+                            openContentModal(provider.provider_type, provider);
                           }
-                          onMouseLeave={() => setHoveredButtonKey(null)}
-                          action={true}
-                          tertiary
-                          disabled={buttonState.disabled}
-                          onClick={(e) => {
-                            e.stopPropagation();
-                            buttonState.onClick?.();
-                          }}
-                        >
-                          {buttonState.label}
-                        </HoverIconButton>
-                      ) : (
-                        <Disabled
-                          disabled={
-                            buttonState.disabled || !buttonState.onClick
-                          }
-                        >
-                          <OpalButton
-                            prominence="tertiary"
-                            onClick={(e) => {
-                              e.stopPropagation();
-                              buttonState.onClick?.();
-                            }}
-                            rightIcon={
-                              buttonState.icon === "arrow"
-                                ? SvgArrowExchange
-                                : buttonState.icon === "arrow-circle"
-                                  ? SvgArrowRightCircle
-                                  : undefined
-                            }
-                          >
-                            {buttonState.label}
-                          </OpalButton>
-                        </Disabled>
-                      )}
-                    </div>
-                  </div>
+                        : undefined
+                    }
+                    onDisconnect={
+                      provider.provider_type !== "onyx_web_crawler" &&
+                      isConfigured &&
+                      provider.id > 0
+                        ? () =>
+                            setDisconnectTarget({
+                              id: provider.id,
+                              label,
+                              category: "content",
+                              providerType: provider.provider_type,
+                            })
+                        : undefined
+                    }
+                  />
                 );
               })}
             </div>
@@ -1238,6 +1273,21 @@ export default function Page() {
         </SettingsLayouts.Body>
       </SettingsLayouts.Root>
 
+      {disconnectTarget && (
+        <WebSearchDisconnectModal
+          disconnectTarget={disconnectTarget}
+          searchProviders={searchProviders}
+          contentProviders={combinedContentProviders}
+          replacementProviderId={replacementProviderId}
+          onReplacementChange={setReplacementProviderId}
+          onClose={() => {
+            setDisconnectTarget(null);
+            setReplacementProviderId(null);
+          }}
+          onDisconnect={() => void handleDisconnectProvider()}
+        />
+      )}
+
       <WebProviderSetupModal
         isOpen={selectedProviderType !== null}
         onClose={() => {

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

@@ -9,7 +9,7 @@ import {
   TableCell,
   TableHeader,
 } from "@/components/ui/table";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import { Callout } from "@/components/ui/callout";
 import { CCPairFullInfo } from "./types";
 import { IndexAttemptSnapshot } from "@/lib/types";
@@ -153,17 +153,11 @@ export function IndexAttemptsTable({
                   </div>
                 </TableCell>
                 <TableCell>
-                  {indexAttempt.status === "success" && (
-                    <Text className="flex flex-wrap whitespace-normal">
-                      {"-"}
-                    </Text>
-                  )}
+                  {indexAttempt.status === "success" && <Text as="p">-</Text>}
 
                   {indexAttempt.status === "failed" &&
                     indexAttempt.error_msg && (
-                      <Text className="flex flex-wrap whitespace-normal">
-                        {indexAttempt.error_msg}
-                      </Text>
+                      <Text as="p">{indexAttempt.error_msg}</Text>
                     )}
                 </TableCell>
                 <td className="w-0 p-0">

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

@@ -11,9 +11,10 @@ import {
   TableHeader,
   TableRow,
 } from "@/components/ui/table";
-import { Button } from "@opal/components";
+import { Button, Text } from "@opal/components";
 import { Card } from "@/components/ui/card";
-import Text from "@/components/ui/text";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import { Spinner } from "@/components/Spinner";
 import { SvgDownloadCloud } from "@opal/icons";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
@@ -75,11 +76,12 @@ function Main() {
     <>
       {isDownloading && <Spinner />}
       <div className="mb-8">
-        <Text className="mb-3">
-          <b>Debug Logs</b> provide detailed information about system operations
-          and events. You can download logs for each category to analyze system
-          behavior or troubleshoot issues.
+        <Text as="p">
+          {markdown(
+            "**Debug Logs** provide detailed information about system operations and events. You can download logs for each category to analyze system behavior or troubleshoot issues."
+          )}
         </Text>
+        <Spacer rem={0.75} />
 
         {categories.length > 0 && (
           <Card className="mt-4">

web/src/app/admin/documents/sets/page.tsx

@@ -10,7 +10,9 @@ import {
   TableBody,
   TableCell,
 } from "@/components/ui/table";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Title from "@/components/ui/title";
 import Separator from "@/refresh-components/Separator";
 import { DocumentSetSummary } from "@/lib/types";
@@ -393,11 +395,12 @@ function Main() {
 
   return (
     <div className="mb-8">
-      <Text className="mb-3">
-        <b>Document Sets</b> allow you to group logically connected documents
-        into a single bundle. These can then be used as a filter when performing
-        searches to control the scope of information Onyx searches over.
+      <Text as="p">
+        {markdown(
+          "**Document Sets** allow you to group logically connected documents into a single bundle. These can then be used as a filter when performing searches to control the scope of information Onyx searches over."
+        )}
       </Text>
+      <Spacer rem={0.75} />
 
       <div className="mb-3"></div>
 

web/src/app/admin/embeddings/pages/CloudEmbeddingPage.tsx

@@ -1,6 +1,8 @@
 "use client";
 
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Title from "@/components/ui/title";
 import {
   CloudEmbeddingProvider,
@@ -99,10 +101,12 @@ export default function CloudEmbeddingPage({
       <Title className="mt-8">
         Here are some cloud-based models to choose from.
       </Title>
-      <Text className="mb-4">
-        These models require API keys and run in the clouds of the respective
-        providers.
+      <Text as="p">
+        {
+          "These models require API keys and run in the clouds of the respective providers."
+        }
       </Text>
+      <Spacer rem={1} />
 
       <div className="gap-4 mt-2 pb-10 flex content-start flex-wrap">
         {providers.map((provider) => (
@@ -156,18 +160,11 @@ export default function CloudEmbeddingPage({
           </div>
         ))}
 
-        <Text className="mt-6">
-          Alternatively, you can use a self-hosted model using the LiteLLM
-          proxy. This allows you to leverage various LLM providers through a
-          unified interface that you control.{" "}
-          <a
-            href="https://docs.litellm.ai/"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-blue-500 hover:underline"
-          >
-            Learn more about LiteLLM
-          </a>
+        <Spacer rem={1.5} />
+        <Text as="p">
+          {markdown(
+            "Alternatively, you can use a self-hosted model using the LiteLLM proxy. This allows you to leverage various LLM providers through a unified interface that you control. [Learn more about LiteLLM](https://docs.litellm.ai/)"
+          )}
         </Text>
 
         <div key={LITELLM_CLOUD_PROVIDER.provider_type} className="mt-4 w-full">
@@ -214,20 +211,25 @@ export default function CloudEmbeddingPage({
             {!liteLLMProvider && (
               <CardSection className="mt-2 w-full max-w-4xl bg-background-50 border border-background-200">
                 <div className="p-4">
-                  <Text className="text-lg font-semibold mb-2">
+                  <Text as="p" font="heading-h3">
                     API URL Required
                   </Text>
-                  <Text className="text-sm text-text-600 mb-4">
-                    Before you can add models, you need to provide an API URL
-                    for your LiteLLM proxy. Click the &quot;Provide API
-                    URL&quot; button above to set up your LiteLLM configuration.
+                  <Spacer rem={0.5} />
+                  <Text as="p">
+                    {
+                      'Before you can add models, you need to provide an API URL for your LiteLLM proxy. Click the "Provide API URL" button above to set up your LiteLLM configuration.'
+                    }
                   </Text>
+                  <Spacer rem={1} />
                   <div className="flex items-center">
                     <FiInfo className="text-blue-500 mr-2" size={18} />
-                    <Text className="text-sm text-blue-500">
-                      Once configured, you&apos;ll be able to add and manage
-                      your LiteLLM models here.
-                    </Text>
+                    <span className="text-blue-500">
+                      <Text as="p">
+                        {
+                          "Once configured, you'll be able to add and manage your LiteLLM models here."
+                        }
+                      </Text>
+                    </span>
                   </div>
                 </div>
               </CardSection>
@@ -281,9 +283,11 @@ export default function CloudEmbeddingPage({
           </div>
         </div>
 
-        <Text className="mt-6">
-          You can also use Azure OpenAI models for embeddings. Azure requires
-          separate configuration for each model.
+        <Spacer rem={1.5} />
+        <Text as="p">
+          {
+            "You can also use Azure OpenAI models for embeddings. Azure requires separate configuration for each model."
+          }
         </Text>
 
         <div key={AZURE_CLOUD_PROVIDER.provider_type} className="mt-4 w-full">
@@ -319,18 +323,22 @@ export default function CloudEmbeddingPage({
               </button>
               <div className="mt-2 w-full max-w-4xl">
                 <CardSection className="p-4 border border-background-200 rounded-lg shadow-sm">
-                  <Text className="text-base font-medium mb-2">
+                  <Text as="p" font="main-ui-action">
                     Configure Azure OpenAI for Embeddings
                   </Text>
-                  <Text className="text-sm text-text-600 mb-3">
-                    Click &quot;Configure Azure OpenAI&quot; to set up Azure
-                    OpenAI for embeddings.
+                  <Spacer rem={0.5} />
+                  <Text as="p">
+                    {
+                      'Click "Configure Azure OpenAI" to set up Azure OpenAI for embeddings.'
+                    }
                   </Text>
-                  <div className="flex items-center text-sm text-text-700">
+                  <Spacer rem={0.75} />
+                  <div className="flex items-center">
                     <FiInfo className="text-neutral-400 mr-2" size={16} />
-                    <Text>
-                      You&apos;ll need: API version, base URL, API key, model
-                      name, and deployment name.
+                    <Text as="p">
+                      {
+                        "You'll need: API version, base URL, API key, model name, and deployment name."
+                      }
                     </Text>
                   </div>
                 </CardSection>
@@ -339,9 +347,10 @@ export default function CloudEmbeddingPage({
           ) : (
             <>
               <div className="mb-6 w-full">
-                <Text className="text-lg font-semibold mb-3">
+                <Text as="p" font="heading-h3">
                   Current Azure Configuration
                 </Text>
+                <Spacer rem={0.75} />
 
                 {azureProviderDetails ? (
                   <CardSection className="bg-white shadow-sm border border-background-200 rounded-lg">

web/src/app/admin/embeddings/pages/OpenEmbeddingPage.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import Button from "@/refresh-components/buttons/Button";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Title from "@/components/ui/title";
 import { ModelSelector } from "../../../../components/embedding/ModelSelector";
 import {
@@ -25,41 +27,28 @@ export default function OpenEmbeddingPage({
       <Title className="mt-8">
         Here are some locally-hosted models to choose from.
       </Title>
-      <Text className="mb-4">
-        These models can be used without any API keys, and can leverage a GPU
-        for faster inference.
+      <Text as="p">
+        {
+          "These models can be used without any API keys, and can leverage a GPU for faster inference."
+        }
       </Text>
+      <Spacer rem={1} />
       <ModelSelector
         modelOptions={AVAILABLE_MODELS}
         setSelectedModel={onSelectOpenSource}
         currentEmbeddingModel={selectedProvider}
       />
 
-      <Text className="mt-6">
-        Alternatively, (if you know what you&apos;re doing) you can specify a{" "}
-        <a
-          target="_blank"
-          href="https://www.sbert.net/"
-          className="text-link"
-          rel="noreferrer"
-        >
-          SentenceTransformers
-        </a>
-        -compatible model of your choice below. The rough list of supported
-        models can be found{" "}
-        <a
-          target="_blank"
-          href="https://huggingface.co/models?library=sentence-transformers&sort=trending"
-          className="text-link"
-          rel="noreferrer"
-        >
-          here
-        </a>
-        .
-        <br />
-        <b>NOTE:</b> not all models listed will work with Onyx, since some have
-        unique interfaces or special requirements. If in doubt, reach out to the
-        Onyx team.
+      <Spacer rem={1.5} />
+      <Text as="p">
+        {markdown(
+          "Alternatively, (if you know what you're doing) you can specify a [SentenceTransformers](https://www.sbert.net/)-compatible model of your choice below. The rough list of supported models can be found [here](https://huggingface.co/models?library=sentence-transformers&sort=trending)."
+        )}
+      </Text>
+      <Text as="p">
+        {markdown(
+          "**NOTE:** not all models listed will work with Onyx, since some have unique interfaces or special requirements. If in doubt, reach out to the Onyx team."
+        )}
       </Text>
       {!configureModel && (
         // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved

web/src/app/admin/indexing/status/page.tsx

@@ -5,7 +5,9 @@ import { SearchAndFilterControls } from "./SearchAndFilterControls";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Link from "next/link";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import { useConnectorIndexingStatusWithPagination } from "@/lib/hooks";
 import { useToastFromQuery } from "@/hooks/useToast";
 import { Button } from "@opal/components";
@@ -185,13 +187,14 @@ function Main() {
           <ConnectorStaggeredSkeleton rowCount={8} standalone={true} />
         </div>
       ) : !ccPairsIndexingStatuses || ccPairsIndexingStatuses.length === 0 ? (
-        <Text className="mt-12">
-          It looks like you don&apos;t have any connectors setup yet. Visit the{" "}
-          <Link className="text-link" href="/admin/add-connector">
-            Add Connector
-          </Link>{" "}
-          page to get started!
-        </Text>
+        <div>
+          <Spacer rem={3} />
+          <Text as="p">
+            {markdown(
+              "It looks like you don't have any connectors setup yet. Visit the [Add Connector](/admin/add-connector) page to get started!"
+            )}
+          </Text>
+        </div>
       ) : (
         <CCPairIndexingStatusTable
           ccPairsIndexingStatuses={ccPairsIndexingStatuses}

web/src/app/admin/token-rate-limits/TokenRateLimitTables.tsx

@@ -16,7 +16,8 @@ import { errorHandlingFetcher } from "@/lib/fetcher";
 import useSWR, { mutate } from "swr";
 import Checkbox from "@/refresh-components/inputs/Checkbox";
 import { TableHeader } from "@/components/ui/table";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import Spacer from "@/refresh-components/Spacer";
 
 type TokenRateLimitTableArgs = {
   tokenRateLimits: TokenRateLimitDisplay[];
@@ -68,11 +69,15 @@ export const TokenRateLimitTable = ({
       <div className="w-full">
         {!hideHeading && title && <Title>{title}</Title>}
         {!hideHeading && description && (
-          <Text className="my-2">{description}</Text>
+          <>
+            <Spacer rem={0.5} />
+            <Text as="p">{description}</Text>
+            <Spacer rem={0.5} />
+          </>
         )}
-        <Text className={`${!hideHeading && "my-8"}`}>
-          No token rate limits set!
-        </Text>
+        {!hideHeading && <Spacer rem={2} />}
+        <Text as="p">No token rate limits set!</Text>
+        {!hideHeading && <Spacer rem={2} />}
       </div>
     );
   }
@@ -81,7 +86,11 @@ export const TokenRateLimitTable = ({
     <div className="w-full">
       {!hideHeading && title && <Title>{title}</Title>}
       {!hideHeading && description && (
-        <Text className="my-2">{description}</Text>
+        <>
+          <Spacer rem={0.5} />
+          <Text as="p">{description}</Text>
+          <Spacer rem={0.5} />
+        </>
       )}
       <Table
         className={`overflow-visible ${
@@ -188,7 +197,7 @@ export const GenericTokenRateLimitTable = ({
   }
 
   if (!isLoading && error) {
-    return <Text>Failed to load token rate limits</Text>;
+    return <Text as="p">Failed to load token rate limits</Text>;
   }
 
   let processedData = data;

web/src/app/admin/token-rate-limits/page.tsx

@@ -2,7 +2,7 @@
 
 import SimpleTabs from "@/refresh-components/SimpleTabs";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import { useState } from "react";
 import {
   insertGlobalTokenRateLimit,
@@ -104,14 +104,14 @@ function Main() {
 
   return (
     <Section alignItems="stretch" justifyContent="start" height="auto">
-      <Text>
+      <Text as="p">
         Token rate limits enable you control how many tokens can be spent in a
         given time period. With token rate limits, you can:
       </Text>
 
       <ul className="list-disc ml-4">
         <li>
-          <Text>
+          <Text as="p">
             Set a global rate limit to control your team&apos;s overall token
             spend.
           </Text>
@@ -119,13 +119,13 @@ function Main() {
         {isPaidEnterpriseFeaturesEnabled && (
           <>
             <li>
-              <Text>
+              <Text as="p">
                 Set rate limits for users to ensure that no single user can
                 spend too many tokens.
               </Text>
             </li>
             <li>
-              <Text>
+              <Text as="p">
                 Set rate limits for user groups to control token spend for your
                 teams.
               </Text>
@@ -133,7 +133,7 @@ function Main() {
           </>
         )}
         <li>
-          <Text>Enable and disable rate limits on the fly.</Text>
+          <Text as="p">Enable and disable rate limits on the fly.</Text>
         </li>
       </ul>
 

web/src/app/auth/forgot-password/page.tsx

@@ -3,7 +3,9 @@ import React, { useState } from "react";
 import { forgotPassword } from "./utils";
 import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
 import Title from "@/components/ui/title";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Link from "next/link";
 import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
@@ -73,12 +75,11 @@ const ForgotPasswordPage: React.FC = () => {
             </Form>
           )}
         </Formik>
+        <Spacer rem={1} />
         <div className="flex">
-          <Text className="mt-4 mx-auto">
-            <Link href="/auth/login" className="text-link font-medium">
-              Back to Login
-            </Link>
-          </Text>
+          <div className="mx-auto">
+            <Text as="p">{markdown("[Back to Login](/auth/login)")}</Text>
+          </div>
         </div>
       </div>
     </AuthFlowContainer>

web/src/app/auth/reset-password/page.tsx

@@ -3,7 +3,9 @@ import React, { useState, useEffect } from "react";
 import { resetPassword } from "../forgot-password/utils";
 import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
 import Title from "@/components/ui/title";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import Link from "next/link";
 import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
@@ -109,12 +111,11 @@ const ResetPasswordPage: React.FC = () => {
             </Form>
           )}
         </Formik>
+        <Spacer rem={1} />
         <div className="flex">
-          <Text className="mt-4 mx-auto">
-            <Link href="/auth/login" className="text-link font-medium">
-              Back to Login
-            </Link>
-          </Text>
+          <div className="mx-auto">
+            <Text as="p">{markdown("[Back to Login](/auth/login)")}</Text>
+          </div>
         </div>
       </div>
     </AuthFlowContainer>

web/src/app/auth/verify-email/Verify.tsx

@@ -2,7 +2,8 @@
 
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useState } from "react";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import Spacer from "@/refresh-components/Spacer";
 import { RequestNewVerificationEmail } from "../waiting-on-verification/RequestNewVerificationEmail";
 import { User } from "@/lib/types";
 import Logo from "@/refresh-components/Logo";
@@ -65,17 +66,22 @@ export default function Verify({ user }: VerifyProps) {
       <div className="min-h-screen flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
         <Logo folded size={64} className="mx-auto w-fit animate-pulse" />
         {!error ? (
-          <Text className="mt-2">Verifying your email...</Text>
+          <>
+            <Spacer rem={0.5} />
+            <Text as="p">Verifying your email...</Text>
+          </>
         ) : (
           <div>
-            <Text className="mt-2">{error}</Text>
+            <Spacer rem={0.5} />
+            <Text as="p">{error}</Text>
 
             {user && (
               <div className="text-center">
                 <RequestNewVerificationEmail email={user.email}>
-                  <Text className="mt-2 text-link">
+                  {/* TODO(@raunakab): migrate to @opal/components Text */}
+                  <p className="text-sm mt-2 text-link">
                     Get new verification email
-                  </Text>
+                  </p>
                 </RequestNewVerificationEmail>
               </div>
             )}

web/src/app/auth/waiting-on-verification/page.tsx

@@ -4,11 +4,11 @@ import {
   getCurrentUserSS,
 } from "@/lib/userSS";
 import { redirect } from "next/navigation";
-
 import { User } from "@/lib/types";
-import Text from "@/components/ui/text";
 import { RequestNewVerificationEmail } from "./RequestNewVerificationEmail";
 import Logo from "@/refresh-components/Logo";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
 
 export default async function Page() {
   // catch cases where the backend is completely unreachable here
@@ -35,22 +35,21 @@ export default async function Page() {
 
   return (
     <main>
-      <div className="min-h-screen flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
+      <div className="min-h-screen flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8 gap-4">
         <Logo folded size={64} className="mx-auto w-fit" />
-        <div className="flex">
-          <Text className="text-center font-medium text-lg mt-6 w-108">
-            Hey <i>{currentUser.email}</i> - it looks like you haven&apos;t
-            verified your email yet.
-            <br />
-            Check your inbox for an email from us to get started!
-            <br />
-            <br />
-            If you don&apos;t see anything, click{" "}
-            <RequestNewVerificationEmail email={currentUser.email}>
-              here
-            </RequestNewVerificationEmail>{" "}
-            to request a new email.
+        <div className="flex flex-col gap-2">
+          <Text as="span">
+            {markdown(
+              `Hey, *${currentUser.email}*, it looks like you haven't verified your email yet.\nCheck your inbox for an email from us to get started!`
+            )}
           </Text>
+          <div className="flex flex-row items-center gap-1">
+            <Text as="span">If you don't see anything, click</Text>
+            <RequestNewVerificationEmail email={currentUser.email}>
+              <Text as="span">here</Text>
+            </RequestNewVerificationEmail>
+            <Text as="span">to request a new email.</Text>
+          </div>
         </div>
       </div>
     </main>

web/src/app/css/inputs.css

@@ -19,6 +19,10 @@
   background-color: var(--background-neutral-00);
   border: 1px solid var(--status-error-05);
 }
+.input-error:focus:not(:active),
+.input-error:focus-within:not(:active) {
+  box-shadow: inset 0px 0px 0px 2px var(--background-tint-04);
+}
 
 .input-disabled {
   background-color: var(--background-neutral-03);

web/src/app/ee/admin/performance/custom-analytics/CustomAnalyticsUpdateForm.tsx

@@ -3,9 +3,9 @@
 import { Label, SubLabel } from "@/components/Field";
 import { toast } from "@/hooks/useToast";
 import { SettingsContext } from "@/providers/SettingsProvider";
-import { Button } from "@opal/components";
+import { Button, Text } from "@opal/components";
+import { markdown } from "@opal/utils";
 import { Callout } from "@/components/ui/callout";
-import Text from "@/components/ui/text";
 import { useContext, useState } from "react";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
 import Spacer from "@/refresh-components/Spacer";
@@ -54,17 +54,17 @@ export function CustomAnalyticsUpdateForm() {
       >
         <div className="mb-4">
           <Label>Script</Label>
-          <Text className="mb-3">
+          <Text as="p">
             Specify the Javascript that should run on page load in order to
             initialize your custom tracking/analytics.
           </Text>
-          <Text className="mb-2">
-            Do not include the{" "}
-            <span className="font-mono">&lt;script&gt;&lt;/script&gt;</span>{" "}
-            tags. If you upload a script below but you are not recieving any
-            events in your analytics platform, try removing all extra whitespace
-            before each line of JavaScript.
+          <Spacer rem={0.75} />
+          <Text as="p">
+            {markdown(
+              "Do not include the `<script></script>` tags. If you upload a script below but you are not receiving any events in your analytics platform, try removing all extra whitespace before each line of JavaScript."
+            )}
           </Text>
+          <Spacer rem={0.5} />
           <InputTextArea
             value={newCustomAnalyticsScript}
             onChange={(event) =>

web/src/app/ee/admin/performance/custom-analytics/page.tsx

@@ -2,7 +2,8 @@ import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { CUSTOM_ANALYTICS_ENABLED } from "@/lib/constants";
 import { Callout } from "@/components/ui/callout";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import Spacer from "@/refresh-components/Spacer";
 import { CustomAnalyticsUpdateForm } from "./CustomAnalyticsUpdateForm";
 
 const route = ADMIN_ROUTES.CUSTOM_ANALYTICS;
@@ -24,11 +25,12 @@ function Main() {
 
   return (
     <div>
-      <Text className="mb-8">
-        This allows you to bring your own analytics tool to Onyx! Copy the Web
-        snippet from your analytics provider into the box below, and we&apos;ll
-        start sending usage events.
+      <Text as="p">
+        {
+          "This allows you to bring your own analytics tool to Onyx! Copy the Web snippet from your analytics provider into the box below, and we'll start sending usage events."
+        }
       </Text>
+      <Spacer rem={2} />
 
       <CustomAnalyticsUpdateForm />
     </div>

web/src/app/ee/admin/performance/query-history/[id]/page.tsx

@@ -1,9 +1,10 @@
 "use client";
 import { use } from "react";
 
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 import Separator from "@/refresh-components/Separator";
+import Spacer from "@/refresh-components/Spacer";
 import { ChatSessionSnapshot, MessageSnapshot } from "../../usage/types";
 import { FiBook } from "react-icons/fi";
 import { timestampToReadableDate } from "@/lib/dateUtils";
@@ -21,13 +22,13 @@ function MessageDisplay({ message }: { message: MessageSnapshot }) {
       <p className="text-xs font-bold mb-1">
         {message.message_type === "user" ? "User" : "AI"}
       </p>
-      <Text>{message.message}</Text>
+      <Text as="p">{message.message}</Text>
       {message.documents.length > 0 && (
         <div className="flex flex-col gap-y-2 mt-2">
           <p className="font-bold text-xs">Reference Documents</p>
           {message.documents.slice(0, 5).map((document) => {
             return (
-              <Text className="flex" key={document.document_id}>
+              <div className="text-sm flex" key={document.document_id}>
                 <FiBook
                   className={
                     "my-auto mr-1" + (document.link ? " text-link" : " ")
@@ -45,7 +46,7 @@ function MessageDisplay({ message }: { message: MessageSnapshot }) {
                 ) : (
                   document.semantic_identifier
                 )}
-              </Text>
+              </div>
             );
           })}
         </div>
@@ -53,7 +54,7 @@ function MessageDisplay({ message }: { message: MessageSnapshot }) {
       {message.feedback_type && (
         <div className="mt-2">
           <p className="font-bold text-xs">Feedback</p>
-          {message.feedback_text && <Text>{message.feedback_text}</Text>}
+          {message.feedback_text && <Text as="p">{message.feedback_text}</Text>}
           <div className="mt-1">
             <FeedbackBadge feedback={message.feedback_type} />
           </div>
@@ -95,14 +96,19 @@ export default function QueryPage(props: { params: Promise<{ id: string }> }) {
       <CardSection className="mt-4">
         <Title>Chat Session Details</Title>
 
-        <Text className="flex flex-wrap whitespace-normal mt-1 text-sm">
-          {chatSessionSnapshot.assistant_name}
-        </Text>
-        <Text className="flex flex-wrap whitespace-normal mt-1 text-xs">
-          {chatSessionSnapshot.user_email &&
-            `${chatSessionSnapshot.user_email}, `}
-          {timestampToReadableDate(chatSessionSnapshot.time_created)},{" "}
-          {chatSessionSnapshot.flow_type}
+        <Spacer rem={0.25} />
+        {chatSessionSnapshot.assistant_name && (
+          <Text as="p">{chatSessionSnapshot.assistant_name}</Text>
+        )}
+        <Spacer rem={0.25} />
+        <Text as="p">
+          {`${
+            chatSessionSnapshot.user_email
+              ? `${chatSessionSnapshot.user_email}, `
+              : ""
+          }${timestampToReadableDate(chatSessionSnapshot.time_created)}, ${
+            chatSessionSnapshot.flow_type
+          }`}
         </Text>
 
         <Separator />

web/src/app/ee/admin/performance/usage/FeedbackChart.tsx

@@ -1,6 +1,6 @@
 import { ThreeDotsLoader } from "@/components/Loading";
 import { getDatesList, useQueryAnalytics } from "../lib";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 
 import { DateRangePickerValue } from "@/components/dateRangeSelectors/AdminDateRangeSelector";
@@ -68,7 +68,7 @@ export function FeedbackChart({
   return (
     <CardSection className="mt-8">
       <Title>Feedback</Title>
-      <Text>Thumbs Up / Thumbs Down over time</Text>
+      <Text as="p">Thumbs Up / Thumbs Down over time</Text>
       {chart}
     </CardSection>
   );

web/src/app/ee/admin/performance/usage/OnyxBotChart.tsx

@@ -1,7 +1,7 @@
 import { ThreeDotsLoader } from "@/components/Loading";
 import { getDatesList, useOnyxBotAnalytics } from "../lib";
 import { DateRangePickerValue } from "@/components/dateRangeSelectors/AdminDateRangeSelector";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 import CardSection from "@/components/admin/CardSection";
 import { AreaChartDisplay } from "@/components/ui/areaChart";
@@ -69,7 +69,7 @@ export function OnyxBotChart({
   return (
     <CardSection className="mt-8">
       <Title>Slack Channel</Title>
-      <Text>Total Queries vs Auto Resolved</Text>
+      <Text as="p">Total Queries vs Auto Resolved</Text>
       {chart}
     </CardSection>
   );

web/src/app/ee/admin/performance/usage/PersonaMessagesChart.tsx

@@ -6,7 +6,7 @@ import {
   usePersonaUniqueUsers,
 } from "../lib";
 import { DateRangePickerValue } from "@/components/dateRangeSelectors/AdminDateRangeSelector";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 import CardSection from "@/components/admin/CardSection";
 import { AreaChartDisplay } from "@/components/ui/areaChart";
@@ -180,7 +180,9 @@ export function PersonaMessagesChart({
     <CardSection className="mt-8">
       <Title>Agent Analytics</Title>
       <div className="flex flex-col gap-4">
-        <Text>Messages and unique users per day for the selected agent</Text>
+        <Text as="p">
+          Messages and unique users per day for the selected agent
+        </Text>
         <div className="flex items-center gap-4">
           <Select
             value={selectedPersonaId?.toString() ?? ""}

web/src/app/ee/admin/performance/usage/QueryPerformanceChart.tsx

@@ -5,7 +5,7 @@ import { getDatesList, useQueryAnalytics, useUserAnalytics } from "../lib";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { AreaChartDisplay } from "@/components/ui/areaChart";
 import Title from "@/components/ui/title";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import CardSection from "@/components/admin/CardSection";
 
 export function QueryPerformanceChart({
@@ -98,7 +98,7 @@ export function QueryPerformanceChart({
   return (
     <CardSection className="mt-8">
       <Title>Usage</Title>
-      <Text>Usage over time</Text>
+      <Text as="p">Usage over time</Text>
       {chart}
     </CardSection>
   );

web/src/app/ee/admin/performance/usage/UsageReports.tsx

@@ -12,8 +12,9 @@ import {
   TableHeader,
   TableRow,
 } from "@/components/ui/table";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
+import Spacer from "@/refresh-components/Spacer";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
 import { Disabled } from "@opal/core";
@@ -98,9 +99,8 @@ function GenerateReportInput({
   return (
     <div className="mb-8">
       <Title className="mb-2">Generate Usage Reports</Title>
-      <Text className="mb-8">
-        Generate usage statistics for users in the workspace.
-      </Text>
+      <Text as="p">Generate usage statistics for users in the workspace.</Text>
+      <Spacer rem={2} />
       <div className="grid gap-2 mb-3">
         <Popover>
           <Popover.Trigger asChild>
@@ -412,9 +412,9 @@ export default function UsageReports() {
           isWaitingForReport={isWaitingForReport}
         />
         {timeoutMessage && (
-          <div className="mb-4 p-4 bg-amber-50 dark:bg-amber-950/20 border border-amber-200 dark:border-amber-800 rounded-regular">
+          <div className="mb-4 p-4 bg-status-warning-00 border border-status-warning-02 rounded-regular">
             <div className="flex items-start gap-2">
-              <div className="text-amber-600 dark:text-amber-500 mt-0.5">
+              <div className="text-status-warning-05 mt-0.5">
                 <svg
                   className="w-5 h-5"
                   fill="none"
@@ -430,12 +430,15 @@ export default function UsageReports() {
                 </svg>
               </div>
               <div className="flex-1">
-                <Text className="text-amber-800 dark:text-amber-200 font-medium mb-1">
-                  Report Generation In Progress
-                </Text>
-                <Text className="text-amber-700 dark:text-amber-300 text-sm">
-                  {timeoutMessage}
-                </Text>
+                <div className="text-status-warning-05">
+                  <Text as="p" font="main-ui-action">
+                    Report Generation In Progress
+                  </Text>
+                </div>
+                <Spacer rem={0.25} />
+                <div className="text-status-warning-05">
+                  <Text as="p">{timeoutMessage}</Text>
+                </div>
               </div>
             </div>
           </div>

web/src/app/ee/admin/standard-answer/page.tsx

@@ -25,7 +25,9 @@ import { deleteStandardAnswer } from "./lib";
 import { FilterDropdown } from "@/components/search/filtering/FilterDropdown";
 import { FiTag } from "react-icons/fi";
 import { PageSelector } from "@/components/PageSelector";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import { markdown } from "@opal/utils";
+import Spacer from "@/refresh-components/Spacer";
 import { TableHeader } from "@/components/ui/table";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { SvgEdit, SvgTrash } from "@opal/icons";
@@ -316,19 +318,17 @@ const StandardAnswersTable = ({
         <div>
           {paginatedStandardAnswers.length === 0 && (
             <div className="flex justify-center">
-              <Text>No matching standard answers found...</Text>
+              <Text as="p">No matching standard answers found...</Text>
             </div>
           )}
         </div>
         {paginatedStandardAnswers.length > 0 && (
           <>
             <div className="mt-4">
-              <Text>
-                Ensure that you have added the category to the relevant{" "}
-                <a className="text-link" href="/admin/bots">
-                  Slack Bot
-                </a>
-                .
+              <Text as="p">
+                {markdown(
+                  "Ensure that you have added the category to the relevant [Slack Bot](/admin/bots)."
+                )}
               </Text>
             </div>
             <div className="mt-4 flex justify-center">
@@ -389,14 +389,17 @@ function Main() {
 
   return (
     <div className="mb-8">
-      <Text className="mb-2">
-        Manage the standard answers for pre-defined questions.
-        <br />
-        Note: Currently, only questions asked from Slack can receive standard
-        answers.
+      <Text as="p">
+        {markdown(
+          "Manage the standard answers for pre-defined questions.\nNote: Currently, only questions asked from Slack can receive standard answers."
+        )}
       </Text>
+      <Spacer rem={0.5} />
       {standardAnswers.length == 0 && (
-        <Text className="mb-2">Add your first standard answer below!</Text>
+        <>
+          <Text as="p">Add your first standard answer below!</Text>
+          <Spacer rem={0.5} />
+        </>
       )}
       <div className="mb-2"></div>
 

web/src/components/credentials/CredentialSection.tsx

@@ -16,7 +16,7 @@ import { toast } from "@/hooks/useToast";
 import CreateCredential from "./actions/CreateCredential";
 import { CCPairFullInfo } from "@/app/admin/connector/[ccPairId]/types";
 import ModifyCredential from "./actions/ModifyCredential";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 import {
   buildCCPairInfoUrl,
   buildSimilarCredentialInfoURL,
@@ -185,7 +185,7 @@ export default function CredentialSection({
           <div className="flex-grow flex flex-col justify-center">
             <div className="flex items-center justify-between">
               <div>
-                <Text className="font-medium">
+                <Text as="p">
                   {ccPair.credential.name ||
                     `Credential #${ccPair.credential.id}`}
                 </Text>

web/src/components/credentials/actions/EditCredential.tsx

@@ -1,6 +1,6 @@
 import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
 
 import { FaNewspaper, FaTrash } from "react-icons/fa";
 import { TextFormField, TypedFileUploadFormField } from "@/components/Field";
@@ -51,7 +51,7 @@ export default function EditCredential({
 
   return (
     <div className="flex flex-col gap-y-6">
-      <Text>
+      <Text as="p">
         Ensure that you update to a credential with the proper permissions!
       </Text>
 

web/src/components/embedding/CustomEmbeddingModelForm.tsx

@@ -7,7 +7,8 @@ import { Formik, Form } from "formik";
 import * as Yup from "yup";
 import { TextFormField, BooleanFormField } from "@/components/Field";
 import { Dispatch, SetStateAction } from "react";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import Spacer from "@/refresh-components/Spacer";
 import Button from "@/refresh-components/buttons/Button";
 import { EmbeddingDetails } from "@/app/admin/embeddings/EmbeddingModelSelectionForm";
 
@@ -59,10 +60,12 @@ export function CustomEmbeddingModelForm({
       >
         {({ isSubmitting, submitForm, errors }) => (
           <Form>
-            <Text className="text-xl text-text-900 font-bold mb-4">
-              Specify details for your {getFormattedProviderName(embeddingType)}{" "}
-              Provider&apos;s model
+            <Text as="p" font="heading-h3">
+              {`Specify details for your ${getFormattedProviderName(
+                embeddingType
+              )} Provider's model`}
             </Text>
+            <Spacer rem={1} />
             <TextFormField
               name="model_name"
               label="Model Name:"

web/src/components/embedding/FailedReIndexAttempts.tsx

@@ -13,7 +13,8 @@ import {
   TableHeader,
   TableRow,
 } from "@/components/ui/table";
-import Text from "@/components/ui/text";
+import { Text } from "@opal/components";
+import Spacer from "@/refresh-components/Spacer";
 import Link from "next/link";
 import { useState } from "react";
 import { FiLink, FiMaximize2, FiTrash } from "react-icons/fi";
@@ -68,15 +69,21 @@ export function FailedReIndexAttempts({
         />
       )}
 
-      <Text className="text-status-error-05 font-semibold mb-2">
-        Failed Re-indexing Attempts
-      </Text>
-      <Text className="text-status-error-05 mb-4">
-        The table below shows only the failed re-indexing attempts for existing
-        connectors. These failures require immediate attention. Once all
-        connectors have been re-indexed successfully, the new model will be used
-        for all search queries.
-      </Text>
+      <div className="text-status-error-05">
+        <Text as="p" font="main-ui-action">
+          Failed Re-indexing Attempts
+        </Text>
+      </div>
+      <Spacer rem={0.5} />
+      <div className="text-status-error-05">
+        <Text as="p">
+          The table below shows only the failed re-indexing attempts for
+          existing connectors. These failures require immediate attention. Once
+          all connectors have been re-indexed successfully, the new model will
+          be used for all search queries.
+        </Text>
+      </div>
+      <Spacer rem={1} />
 
       <div>
         <Table>
@@ -114,7 +121,7 @@ export function FailedReIndexAttempts({
 
                     <TableCell>
                       <div>
-                        <Text className="flex flex-wrap whitespace-normal">
+                        <Text as="p">
                           {reindexingProgress.error_msg || "-"}
                         </Text>
                       </div>

web/src/components/icons/icons.test.tsx

@@ -5,6 +5,7 @@
  * and support various display sizes.
  */
 import React from "react";
+import { SvgBifrost } from "@opal/icons";
 import { render } from "@tests/setup/test-utils";
 import { GithubIcon, GitbookIcon, ConfluenceIcon } from "./icons";
 
@@ -51,4 +52,15 @@ describe("Logo Icons", () => {
       render(<GithubIcon size={100} className="custom-class" />);
     }).not.toThrow();
   });
+
+  test("renders the Bifrost icon with theme-aware colors", () => {
+    const { container } = render(
+      <SvgBifrost size={32} className="custom text-red-500 dark:text-black" />
+    );
+    const icon = container.querySelector("svg");
+
+    expect(icon).toBeInTheDocument();
+    expect(icon).toHaveClass("custom", "text-[#33C19E]", "dark:text-white");
+    expect(icon).not.toHaveClass("text-red-500", "dark:text-black");
+  });
 });

web/src/components/ui/text.tsx

@@ -1,11 +0,0 @@
-import { cn } from "@/lib/utils";
-
-export default function Text({
-  children,
-  className,
-}: {
-  children: React.ReactNode;
-  className?: string;
-}) {
-  return <p className={cn("text-sm", className)}>{children}</p>;
-}

web/src/interfaces/llm.ts

@@ -13,6 +13,7 @@ export enum LLMProviderName {
   VERTEX_AI = "vertex_ai",
   BEDROCK = "bedrock",
   LITELLM_PROXY = "litellm_proxy",
+  BIFROST = "bifrost",
   CUSTOM = "custom",
 }
 
@@ -165,6 +166,21 @@ export interface LiteLLMProxyModelResponse {
   model_name: string;
 }
 
+export interface BifrostFetchParams {
+  api_base?: string;
+  api_key?: string;
+  provider_name?: string;
+  signal?: AbortSignal;
+}
+
+export interface BifrostModelResponse {
+  name: string;
+  display_name: string;
+  max_input_tokens: number | null;
+  supports_image_input: boolean;
+  supports_reasoning: boolean;
+}
+
 export interface VertexAIFetchParams {
   model_configurations?: ModelConfiguration[];
 }
@@ -182,5 +198,6 @@ export type FetchModelsParams =
   | OllamaFetchParams
   | OpenRouterFetchParams
   | LiteLLMProxyFetchParams
+  | BifrostFetchParams
   | VertexAIFetchParams
   | LMStudioFetchParams;

web/src/layouts/input-layouts.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+import type { RichStr } from "@opal/types";
+import { resolveStr } from "@opal/components/text/InlineMarkdown";
 import Text from "@/refresh-components/texts/Text";
 import { SvgXOctagon, SvgAlertCircle } from "@opal/icons";
 import { useField, useFormikContext } from "formik";
@@ -12,9 +14,9 @@ interface OrientationLayoutProps {
   disabled?: boolean;
   nonInteractive?: boolean;
   children?: React.ReactNode;
-  title: string;
+  title: string | RichStr;
   titleSuffix?: string;
-  description?: string;
+  description?: string | RichStr;
   optional?: boolean;
   sizePreset?: "main-content" | "main-ui";
 }
@@ -42,7 +44,7 @@ interface OrientationLayoutProps {
  * ```
  */
 export interface VerticalLayoutProps extends OrientationLayoutProps {
-  subDescription?: React.ReactNode;
+  subDescription?: string | RichStr;
 }
 function VerticalInputLayout({
   name,
@@ -70,7 +72,7 @@ function VerticalInputLayout({
       {name && <ErrorLayout name={name} />}
       {subDescription && (
         <Text secondaryBody text03>
-          {subDescription}
+          {resolveStr(subDescription)}
         </Text>
       )}
     </Section>

web/src/lib/admin/voice/svc.ts

@@ -53,6 +53,12 @@ export async function fetchVoicesByType(
   return fetch(`/api/admin/voice/voices?provider_type=${providerType}`);
 }
 
+export async function deleteVoiceProvider(
+  providerId: number
+): Promise<Response> {
+  return fetch(`${VOICE_PROVIDERS_URL}/${providerId}`, { method: "DELETE" });
+}
+
 export async function fetchLLMProviders(): Promise<Response> {
   return fetch("/api/admin/llm/provider");
 }

web/src/lib/llmConfig/providers.ts

@@ -1,5 +1,6 @@
 import type { IconFunctionComponent } from "@opal/types";
 import {
+  SvgBifrost,
   SvgCpu,
   SvgOpenai,
   SvgClaude,
@@ -26,6 +27,7 @@ const PROVIDER_ICONS: Record<string, IconFunctionComponent> = {
   [LLMProviderName.OLLAMA_CHAT]: SvgOllama,
   [LLMProviderName.OPENROUTER]: SvgOpenrouter,
   [LLMProviderName.LM_STUDIO]: SvgLmStudio,
+  [LLMProviderName.BIFROST]: SvgBifrost,
 
   // fallback
   [LLMProviderName.CUSTOM]: SvgServer,
@@ -42,6 +44,7 @@ const PROVIDER_PRODUCT_NAMES: Record<string, string> = {
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
   [LLMProviderName.LM_STUDIO]: "LM Studio",
+  [LLMProviderName.BIFROST]: "Bifrost",
 
   // fallback
   [LLMProviderName.CUSTOM]: "Custom Models",
@@ -58,6 +61,7 @@ const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
   [LLMProviderName.LM_STUDIO]: "LM Studio",
+  [LLMProviderName.BIFROST]: "Bifrost",
 
   // fallback
   [LLMProviderName.CUSTOM]: "Other providers or self-hosted",

web/src/refresh-components/Modal.tsx

@@ -3,9 +3,10 @@
 import React from "react";
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { cn } from "@/lib/utils";
-import type { IconFunctionComponent } from "@opal/types";
+import type { IconFunctionComponent, RichStr } from "@opal/types";
 import { Button } from "@opal/components";
 import { Content } from "@opal/layouts";
+import { toPlainString } from "@opal/components/text/InlineMarkdown";
 import { SvgX } from "@opal/icons";
 import { WithoutStyles } from "@/types";
 import { Section, SectionProps } from "@/layouts/general-layouts";
@@ -424,12 +425,12 @@ ModalContent.displayName = DialogPrimitive.Content.displayName;
  * </Modal.Header>
  * ```
  */
-interface ModalHeaderProps extends WithoutStyles<SectionProps> {
+interface ModalHeaderProps extends Omit<WithoutStyles<SectionProps>, "title"> {
   icon?: IconFunctionComponent;
   moreIcon1?: IconFunctionComponent;
   moreIcon2?: IconFunctionComponent;
-  title: string;
-  description?: string;
+  title: string | RichStr;
+  description?: string | RichStr;
   onClose?: () => void;
 }
 const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
@@ -456,6 +457,7 @@ const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
       <div
         tabIndex={-1}
         ref={closeButtonRef as React.RefObject<HTMLDivElement>}
+        className="outline-none"
       >
         <DialogPrimitive.Close asChild>
           <Button
@@ -502,7 +504,7 @@ const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
                 />
                 {description && (
                   <DialogPrimitive.Description className="hidden">
-                    {description}
+                    {toPlainString(description)}
                   </DialogPrimitive.Description>
                 )}
               </div>

web/src/refresh-components/cards/Select.tsx

@@ -12,6 +12,7 @@ import {
   SvgArrowRightCircle,
   SvgCheckSquare,
   SvgSettings,
+  SvgUnplug,
 } from "@opal/icons";
 
 const containerClasses = {
@@ -35,6 +36,7 @@ export interface SelectProps
   onSelect?: () => void;
   onDeselect?: () => void;
   onEdit?: () => void;
+  onDisconnect?: () => void;
 
   // Labels (customizable)
   connectLabel?: string;
@@ -59,6 +61,7 @@ export default function Select({
   onSelect,
   onDeselect,
   onEdit,
+  onDisconnect,
   connectLabel = "Connect",
   selectLabel = "Set as Default",
   selectedLabel = "Current Default",
@@ -68,7 +71,7 @@ export default function Select({
   disabled,
   ...rest
 }: SelectProps) {
-  const sizeClass = medium ? "h-[3.75rem]" : "h-[4.25rem]";
+  const sizeClass = medium ? "h-[3.75rem]" : "min-h-[3.75rem] max-h-[5.25rem]";
   const containerClass = containerClasses[status];
   const [isHovered, setIsHovered] = useState(false);
 
@@ -121,7 +124,7 @@ export default function Select({
         </div>
 
         {/* Right section - Actions */}
-        <div className="flex items-center justify-end gap-1">
+        <div className="flex flex-col h-full items-end justify-between gap-1">
           {/* Disconnected: Show Connect button */}
           {isDisconnected && (
             <Disabled disabled={disabled || !onConnect}>
@@ -149,18 +152,32 @@ export default function Select({
                   {selectLabel}
                 </SelectButton>
               </Disabled>
-              {onEdit && (
-                <Disabled disabled={disabled}>
-                  <Button
-                    icon={SvgSettings}
-                    tooltip="Edit"
-                    prominence="tertiary"
-                    size="sm"
-                    onClick={noProp(onEdit)}
-                    aria-label={`Edit ${title}`}
-                  />
-                </Disabled>
-              )}
+              <div className="flex px-1 gap-1">
+                {onDisconnect && (
+                  <Disabled disabled={disabled}>
+                    <Button
+                      icon={SvgUnplug}
+                      tooltip="Disconnect"
+                      prominence="tertiary"
+                      size="sm"
+                      onClick={noProp(onDisconnect)}
+                      aria-label={`Disconnect ${title}`}
+                    />
+                  </Disabled>
+                )}
+                {onEdit && (
+                  <Disabled disabled={disabled}>
+                    <Button
+                      icon={SvgSettings}
+                      tooltip="Edit"
+                      prominence="tertiary"
+                      size="sm"
+                      onClick={noProp(onEdit)}
+                      aria-label={`Edit ${title}`}
+                    />
+                  </Disabled>
+                )}
+              </div>
             </>
           )}
 
@@ -177,18 +194,32 @@ export default function Select({
                   {selectedLabel}
                 </SelectButton>
               </Disabled>
-              {onEdit && (
-                <Disabled disabled={disabled}>
-                  <Button
-                    icon={SvgSettings}
-                    tooltip="Edit"
-                    prominence="tertiary"
-                    size="sm"
-                    onClick={noProp(onEdit)}
-                    aria-label={`Edit ${title}`}
-                  />
-                </Disabled>
-              )}
+              <div className="flex px-1 gap-1">
+                {onDisconnect && (
+                  <Disabled disabled={disabled}>
+                    <Button
+                      icon={SvgUnplug}
+                      tooltip="Disconnect"
+                      prominence="tertiary"
+                      size="sm"
+                      onClick={noProp(onDisconnect)}
+                      aria-label={`Disconnect ${title}`}
+                    />
+                  </Disabled>
+                )}
+                {onEdit && (
+                  <Disabled disabled={disabled}>
+                    <Button
+                      icon={SvgSettings}
+                      tooltip="Edit"
+                      prominence="tertiary"
+                      size="sm"
+                      onClick={noProp(onEdit)}
+                      aria-label={`Edit ${title}`}
+                    />
+                  </Disabled>
+                )}
+              </div>
             </>
           )}
         </div>

web/src/refresh-components/form/types.ts

@@ -12,7 +12,7 @@ export interface FieldContextType {
 
 export type FormFieldRootProps = React.HTMLAttributes<HTMLDivElement> & {
   name?: string;
-  state: FormFieldState;
+  state?: FormFieldState;
   required?: boolean;
   id?: string;
 };

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

@@ -1,5 +1,6 @@
 "use client";
 
+import { markdown } from "@opal/utils";
 import React, { useCallback, useRef, useState } from "react";
 import { useRouter } from "next/navigation";
 import { Formik, Form, useFormikContext } from "formik";
@@ -23,6 +24,7 @@ import {
   SvgExpand,
   SvgFold,
   SvgExternalLink,
+  SvgAlertCircle,
 } from "@opal/icons";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 import { Content } from "@opal/layouts";
@@ -43,9 +45,8 @@ import {
   PYTHON_TOOL_ID,
   OPEN_URL_TOOL_ID,
 } from "@/app/app/components/tools/constants";
-import { Button } from "@opal/components";
+import { Button, Text, Card as OpalCard } from "@opal/components";
 import Modal from "@/refresh-components/Modal";
-import InputTextArea from "@/refresh-components/inputs/InputTextArea";
 import Switch from "@/refresh-components/inputs/Switch";
 import useMcpServersForAgentEditor from "@/hooks/useMcpServersForAgentEditor";
 import useOpenApiTools from "@/hooks/useOpenApiTools";
@@ -304,7 +305,6 @@ function ChatPreferencesForm() {
 
   // System prompt modal state
   const [systemPromptModalOpen, setSystemPromptModalOpen] = useState(false);
-  const [systemPromptValue, setSystemPromptValue] = useState("");
 
   const saveSettings = useCallback(
     async (updates: Partial<Settings>) => {
@@ -398,14 +398,7 @@ function ChatPreferencesForm() {
             <Button
               prominence="tertiary"
               icon={SvgAddLines}
-              onClick={() => {
-                setSystemPromptValue(
-                  defaultAgentConfig?.system_prompt ??
-                    defaultAgentConfig?.default_system_prompt ??
-                    ""
-                );
-                setSystemPromptModalOpen(true);
-              }}
+              onClick={() => setSystemPromptModalOpen(true)}
             >
               Modify Prompt
             </Button>
@@ -768,55 +761,82 @@ function ChatPreferencesForm() {
         onOpenChange={setSystemPromptModalOpen}
       >
         <Modal.Content width="xl" height="fit">
-          <Modal.Header
-            icon={SvgAddLines}
-            title="System Prompt"
-            description="This base prompt is prepended to all chats, agents, and projects."
-            onClose={() => setSystemPromptModalOpen(false)}
-          />
-          <Modal.Body>
-            <InputTextArea
-              value={systemPromptValue}
-              onChange={(e) => setSystemPromptValue(e.target.value)}
-              placeholder="Enter your system prompt..."
-              rows={8}
-              maxRows={20}
-              autoResize
-            />
-          </Modal.Body>
-          <Modal.Footer>
-            <Button
-              prominence="secondary"
-              onClick={() => setSystemPromptModalOpen(false)}
-            >
-              Cancel
-            </Button>
-            <Button
-              prominence="primary"
-              onClick={async () => {
-                try {
-                  const response = await fetch("/api/admin/default-assistant", {
-                    method: "PATCH",
-                    headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify({
-                      system_prompt: systemPromptValue,
-                    }),
-                  });
-                  if (!response.ok) {
-                    const errorMsg = (await response.json()).detail;
-                    throw new Error(errorMsg);
-                  }
-                  await mutateDefaultAgent();
-                  setSystemPromptModalOpen(false);
-                  toast.success("System prompt updated");
-                } catch {
-                  toast.error("Failed to update system prompt");
+          <Formik
+            initialValues={{
+              system_prompt:
+                defaultAgentConfig?.system_prompt ??
+                defaultAgentConfig?.default_system_prompt ??
+                "",
+            }}
+            onSubmit={async ({ system_prompt }) => {
+              try {
+                const response = await fetch("/api/admin/default-assistant", {
+                  method: "PATCH",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({ system_prompt }),
+                });
+                if (!response.ok) {
+                  const errorMsg = (await response.json()).detail;
+                  throw new Error(errorMsg);
                 }
-              }}
-            >
-              Save
-            </Button>
-          </Modal.Footer>
+                await mutateDefaultAgent();
+                setSystemPromptModalOpen(false);
+                toast.success("System prompt updated");
+              } catch {
+                toast.error("Failed to update system prompt");
+              }
+            }}
+          >
+            {({ dirty, isSubmitting, submitForm }) => (
+              <Form>
+                <Modal.Header
+                  icon={SvgAddLines}
+                  title="System Prompt"
+                  description="This base prompt is prepended to all chats, agents, and projects."
+                  onClose={() => setSystemPromptModalOpen(false)}
+                />
+                <Modal.Body>
+                  <Section gap={0.25} alignItems="start">
+                    <InputTextAreaField
+                      name="system_prompt"
+                      placeholder="Enter your system prompt..."
+                      rows={8}
+                      maxRows={20}
+                      autoResize
+                    />
+                    <Text font="secondary-body" color="text-03">
+                      {markdown(
+                        "You can use the following placeholders in your prompt:\n`{{CURRENT_DATETIME}}` - Current date and day of the week in a human-readable format.\n`{{CITATION_GUIDANCE}}` - Instructions for providing citations when facts are retrieved from search tools.\nOnly included when search tools are used."
+                      )}
+                    </Text>
+                  </Section>
+                  <OpalCard backgroundVariant="none" borderVariant="solid">
+                    <Content
+                      sizePreset="main-ui"
+                      icon={SvgAlertCircle}
+                      title="Modify with caution."
+                      description="System prompt affects all chats, agents, and projects. Significant changes may degrade response quality."
+                    />
+                  </OpalCard>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button
+                    prominence="secondary"
+                    onClick={() => setSystemPromptModalOpen(false)}
+                  >
+                    Cancel
+                  </Button>
+                  <Button
+                    prominence="primary"
+                    onClick={submitForm}
+                    disabled={!dirty || isSubmitting}
+                  >
+                    Save
+                  </Button>
+                </Modal.Footer>
+              </Form>
+            )}
+          </Formik>
         </Modal.Content>
       </Modal>
     </>

web/src/refresh-pages/admin/HooksPage/HookFormModal.tsx

@@ -0,0 +1,559 @@
+"use client";
+
+import { useState } from "react";
+import { Button, Text } from "@opal/components";
+import { Disabled } from "@opal/core";
+import {
+  SvgCheckCircle,
+  SvgHookNodes,
+  SvgLoader,
+  SvgRevert,
+} from "@opal/icons";
+import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
+import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
+import { FormField } from "@/refresh-components/form/FormField";
+import { Section } from "@/layouts/general-layouts";
+import { ContentAction } from "@opal/layouts";
+import { toast } from "@/hooks/useToast";
+import {
+  createHook,
+  updateHook,
+  HookAuthError,
+  HookTimeoutError,
+  HookConnectError,
+} from "@/refresh-pages/admin/HooksPage/svc";
+import type {
+  HookFailStrategy,
+  HookFormState,
+  HookPointMeta,
+  HookResponse,
+  HookUpdateRequest,
+} from "@/refresh-pages/admin/HooksPage/interfaces";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface HookFormModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** When provided, the modal is in edit mode for this hook. */
+  hook?: HookResponse;
+  /** When provided (create mode), the hook point is pre-selected and locked. */
+  spec?: HookPointMeta;
+  onSuccess: (hook: HookResponse) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildInitialState(
+  hook: HookResponse | undefined,
+  spec: HookPointMeta | undefined
+): HookFormState {
+  if (hook) {
+    return {
+      name: hook.name,
+      endpoint_url: hook.endpoint_url ?? "",
+      api_key: "",
+      fail_strategy: hook.fail_strategy,
+      timeout_seconds: String(hook.timeout_seconds),
+    };
+  }
+  return {
+    name: "",
+    endpoint_url: "",
+    api_key: "",
+    fail_strategy: spec?.default_fail_strategy ?? "hard",
+    timeout_seconds: spec ? String(spec.default_timeout_seconds) : "30",
+  };
+}
+
+const SOFT_DESCRIPTION =
+  "If the endpoint returns an error, Onyx logs it and continues the pipeline as normal, ignoring the hook result.";
+
+const MAX_TIMEOUT_SECONDS = 600;
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function HookFormModal({
+  open,
+  onOpenChange,
+  hook,
+  spec,
+  onSuccess,
+}: HookFormModalProps) {
+  const isEdit = !!hook;
+  const [form, setForm] = useState<HookFormState>(() =>
+    buildInitialState(hook, spec)
+  );
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isConnected, setIsConnected] = useState(false);
+  // Tracks whether the user explicitly cleared the API key field in edit mode.
+  // - false + empty field  → key unchanged (omitted from PATCH)
+  // - true  + empty field  → key cleared (api_key: null sent to backend)
+  // - false + non-empty    → new key provided (new value sent to backend)
+  const [apiKeyCleared, setApiKeyCleared] = useState(false);
+  const [touched, setTouched] = useState({
+    name: false,
+    endpoint_url: false,
+    api_key: false,
+  });
+  const [apiKeyServerError, setApiKeyServerError] = useState(false);
+  const [endpointServerError, setEndpointServerError] = useState<string | null>(
+    null
+  );
+  const [timeoutServerError, setTimeoutServerError] = useState(false);
+
+  function touch(key: keyof typeof touched) {
+    setTouched((prev) => ({ ...prev, [key]: true }));
+  }
+
+  function handleOpenChange(next: boolean) {
+    if (!next) {
+      if (isSubmitting) return;
+      setTimeout(() => {
+        setForm(buildInitialState(hook, spec));
+        setIsConnected(false);
+        setApiKeyCleared(false);
+        setTouched({ name: false, endpoint_url: false, api_key: false });
+        setApiKeyServerError(false);
+        setEndpointServerError(null);
+        setTimeoutServerError(false);
+      }, 200);
+    }
+    onOpenChange(next);
+  }
+
+  function set<K extends keyof HookFormState>(key: K, value: HookFormState[K]) {
+    setForm((prev) => ({ ...prev, [key]: value }));
+  }
+
+  const timeoutNum = parseFloat(form.timeout_seconds);
+  const isTimeoutValid =
+    !isNaN(timeoutNum) && timeoutNum > 0 && timeoutNum <= MAX_TIMEOUT_SECONDS;
+  const isValid =
+    form.name.trim().length > 0 &&
+    form.endpoint_url.trim().length > 0 &&
+    isTimeoutValid &&
+    (isEdit || form.api_key.trim().length > 0);
+
+  const nameError = touched.name && !form.name.trim();
+  const endpointEmptyError = touched.endpoint_url && !form.endpoint_url.trim();
+  const endpointFieldError = endpointEmptyError
+    ? "Endpoint URL cannot be empty."
+    : endpointServerError ?? undefined;
+  const apiKeyEmptyError = !isEdit && touched.api_key && !form.api_key.trim();
+  const apiKeyFieldError = apiKeyEmptyError
+    ? "API key cannot be empty."
+    : apiKeyServerError
+      ? "Invalid API key."
+      : undefined;
+
+  function handleTimeoutBlur() {
+    if (!isTimeoutValid) {
+      const fallback = hook?.timeout_seconds ?? spec?.default_timeout_seconds;
+      if (fallback !== undefined) {
+        set("timeout_seconds", String(fallback));
+        if (timeoutServerError) setTimeoutServerError(false);
+      }
+    }
+  }
+
+  const hasChanges =
+    isEdit && hook
+      ? form.name !== hook.name ||
+        form.endpoint_url !== (hook.endpoint_url ?? "") ||
+        form.fail_strategy !== hook.fail_strategy ||
+        timeoutNum !== hook.timeout_seconds ||
+        form.api_key.trim().length > 0 ||
+        apiKeyCleared
+      : true;
+
+  async function handleSubmit() {
+    if (!isValid) return;
+
+    setIsSubmitting(true);
+    try {
+      let result: HookResponse;
+      if (isEdit && hook) {
+        const req: HookUpdateRequest = {};
+        if (form.name !== hook.name) req.name = form.name;
+        if (form.endpoint_url !== (hook.endpoint_url ?? ""))
+          req.endpoint_url = form.endpoint_url;
+        if (form.fail_strategy !== hook.fail_strategy)
+          req.fail_strategy = form.fail_strategy;
+        if (timeoutNum !== hook.timeout_seconds)
+          req.timeout_seconds = timeoutNum;
+        if (form.api_key.trim().length > 0) {
+          req.api_key = form.api_key;
+        } else if (apiKeyCleared) {
+          req.api_key = null;
+        }
+        if (Object.keys(req).length === 0) {
+          setIsSubmitting(false);
+          handleOpenChange(false);
+          return;
+        }
+        result = await updateHook(hook.id, req);
+      } else {
+        if (!spec) {
+          toast.error("No hook point specified.");
+          setIsSubmitting(false);
+          return;
+        }
+        result = await createHook({
+          name: form.name,
+          hook_point: spec.hook_point,
+          endpoint_url: form.endpoint_url,
+          ...(form.api_key ? { api_key: form.api_key } : {}),
+          fail_strategy: form.fail_strategy,
+          timeout_seconds: timeoutNum,
+        });
+      }
+      toast.success(isEdit ? "Hook updated." : "Hook created.");
+      onSuccess(result);
+      if (!isEdit) {
+        setIsConnected(true);
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+      setIsSubmitting(false);
+      handleOpenChange(false);
+    } catch (err) {
+      if (err instanceof HookAuthError) {
+        setApiKeyServerError(true);
+      } else if (err instanceof HookTimeoutError) {
+        setTimeoutServerError(true);
+      } else if (err instanceof HookConnectError) {
+        setEndpointServerError(err.message || "Could not connect to endpoint.");
+      } else {
+        toast.error(
+          err instanceof Error ? err.message : "Something went wrong."
+        );
+      }
+      setIsSubmitting(false);
+    }
+  }
+
+  const hookPointDisplayName =
+    spec?.display_name ?? spec?.hook_point ?? hook?.hook_point ?? "";
+  const hookPointDescription = spec?.description;
+  const docsUrl = spec?.docs_url;
+
+  const failStrategyDescription =
+    form.fail_strategy === "soft"
+      ? SOFT_DESCRIPTION
+      : spec?.fail_hard_description;
+
+  return (
+    <Modal open={open} onOpenChange={handleOpenChange}>
+      <Modal.Content width="md" height="fit">
+        <Modal.Header
+          icon={SvgHookNodes}
+          title={isEdit ? "Manage Hook Extension" : "Set Up Hook Extension"}
+          description={
+            isEdit
+              ? undefined
+              : "Connect an external API endpoint to extend the hook point."
+          }
+          onClose={() => handleOpenChange(false)}
+        />
+
+        <Modal.Body>
+          {/* Hook point section header */}
+          <ContentAction
+            sizePreset="main-ui"
+            variant="section"
+            paddingVariant="fit"
+            title={hookPointDisplayName}
+            description={hookPointDescription}
+            rightChildren={
+              <Section
+                flexDirection="column"
+                alignItems="end"
+                width="fit"
+                height="fit"
+                gap={0.25}
+              >
+                <div className="flex items-center gap-1">
+                  <SvgHookNodes
+                    style={{ width: "1rem", height: "1rem" }}
+                    className="text-text-03 shrink-0"
+                  />
+                  <Text font="secondary-body" color="text-03">
+                    Hook Point
+                  </Text>
+                </div>
+                {docsUrl && (
+                  <a
+                    href={docsUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="underline"
+                  >
+                    <Text font="secondary-body" color="text-03">
+                      Documentation
+                    </Text>
+                  </a>
+                )}
+              </Section>
+            }
+          />
+
+          <FormField className="w-full" state={nameError ? "error" : "idle"}>
+            <FormField.Label>Display Name</FormField.Label>
+            <FormField.Control>
+              <div className="[&_input::placeholder]:!font-main-ui-muted w-full">
+                <InputTypeIn
+                  value={form.name}
+                  onChange={(e) => set("name", e.target.value)}
+                  onBlur={() => touch("name")}
+                  placeholder="Name your extension at this hook point"
+                  variant={
+                    isSubmitting ? "disabled" : nameError ? "error" : undefined
+                  }
+                />
+              </div>
+            </FormField.Control>
+            <FormField.Message
+              messages={{ error: "Display name cannot be empty." }}
+            />
+          </FormField>
+
+          <FormField className="w-full">
+            <FormField.Label>Fail Strategy</FormField.Label>
+            <FormField.Control>
+              <InputSelect
+                value={form.fail_strategy}
+                onValueChange={(v) =>
+                  set("fail_strategy", v as HookFailStrategy)
+                }
+                disabled={isSubmitting}
+              >
+                <InputSelect.Trigger placeholder="Select strategy" />
+                <InputSelect.Content>
+                  <InputSelect.Item value="soft">
+                    Log Error and Continue
+                    {spec?.default_fail_strategy === "soft" && (
+                      <>
+                        {" "}
+                        <Text color="text-03">(Default)</Text>
+                      </>
+                    )}
+                  </InputSelect.Item>
+                  <InputSelect.Item value="hard">
+                    Block Pipeline on Failure
+                    {spec?.default_fail_strategy === "hard" && (
+                      <>
+                        {" "}
+                        <Text color="text-03">(Default)</Text>
+                      </>
+                    )}
+                  </InputSelect.Item>
+                </InputSelect.Content>
+              </InputSelect>
+            </FormField.Control>
+            <FormField.Description>
+              {failStrategyDescription}
+            </FormField.Description>
+          </FormField>
+
+          <FormField
+            className="w-full"
+            state={timeoutServerError ? "error" : "idle"}
+          >
+            <FormField.Label>
+              Timeout{" "}
+              <Text font="main-ui-action" color="text-03">
+                (seconds)
+              </Text>
+            </FormField.Label>
+            <FormField.Control>
+              <div className="[&_input]:!font-main-ui-mono [&_input::placeholder]:!font-main-ui-mono [&_input]:![appearance:textfield] [&_input::-webkit-outer-spin-button]:!appearance-none [&_input::-webkit-inner-spin-button]:!appearance-none w-full">
+                <InputTypeIn
+                  type="number"
+                  value={form.timeout_seconds}
+                  onChange={(e) => {
+                    set("timeout_seconds", e.target.value);
+                    if (timeoutServerError) setTimeoutServerError(false);
+                  }}
+                  onBlur={handleTimeoutBlur}
+                  placeholder={
+                    spec ? String(spec.default_timeout_seconds) : undefined
+                  }
+                  variant={
+                    isSubmitting
+                      ? "disabled"
+                      : timeoutServerError
+                        ? "error"
+                        : undefined
+                  }
+                  showClearButton={false}
+                  rightSection={
+                    spec?.default_timeout_seconds !== undefined &&
+                    form.timeout_seconds !==
+                      String(spec.default_timeout_seconds) ? (
+                      <Button
+                        prominence="tertiary"
+                        size="xs"
+                        icon={SvgRevert}
+                        tooltip="Revert to Default"
+                        onClick={() =>
+                          set(
+                            "timeout_seconds",
+                            String(spec.default_timeout_seconds)
+                          )
+                        }
+                        disabled={isSubmitting}
+                      />
+                    ) : undefined
+                  }
+                />
+              </div>
+            </FormField.Control>
+            {!timeoutServerError && (
+              <FormField.Description>
+                Maximum time Onyx will wait for the endpoint to respond before
+                applying the fail strategy. Must be greater than 0 and at most{" "}
+                {MAX_TIMEOUT_SECONDS} seconds.
+              </FormField.Description>
+            )}
+            <FormField.Message
+              messages={{
+                error: "Connection timed out. Try increasing the timeout.",
+              }}
+            />
+          </FormField>
+
+          <FormField
+            className="w-full"
+            state={endpointFieldError ? "error" : "idle"}
+          >
+            <FormField.Label>External API Endpoint URL</FormField.Label>
+            <FormField.Control>
+              <div className="[&_input::placeholder]:!font-main-ui-muted w-full">
+                <InputTypeIn
+                  value={form.endpoint_url}
+                  onChange={(e) => {
+                    set("endpoint_url", e.target.value);
+                    if (endpointServerError) setEndpointServerError(null);
+                  }}
+                  onBlur={() => touch("endpoint_url")}
+                  placeholder="https://your-api-endpoint.com"
+                  variant={
+                    isSubmitting
+                      ? "disabled"
+                      : endpointFieldError
+                        ? "error"
+                        : undefined
+                  }
+                />
+              </div>
+            </FormField.Control>
+            {!endpointFieldError && (
+              <FormField.Description>
+                Only connect to servers you trust. You are responsible for
+                actions taken and data shared with this connection.
+              </FormField.Description>
+            )}
+            <FormField.Message messages={{ error: endpointFieldError }} />
+          </FormField>
+
+          <FormField
+            className="w-full"
+            state={apiKeyFieldError ? "error" : "idle"}
+          >
+            <FormField.Label>API Key</FormField.Label>
+            <FormField.Control>
+              <PasswordInputTypeIn
+                value={form.api_key}
+                onChange={(e) => {
+                  set("api_key", e.target.value);
+                  if (apiKeyServerError) setApiKeyServerError(false);
+                  if (isEdit) {
+                    setApiKeyCleared(
+                      e.target.value === "" && !!hook?.api_key_masked
+                    );
+                  }
+                }}
+                onBlur={() => touch("api_key")}
+                placeholder={
+                  isEdit
+                    ? hook?.api_key_masked ?? "Leave blank to keep current key"
+                    : undefined
+                }
+                disabled={isSubmitting}
+                error={!!apiKeyFieldError}
+              />
+            </FormField.Control>
+            {!apiKeyFieldError && (
+              <FormField.Description>
+                Onyx will use this key to authenticate with your API endpoint.
+              </FormField.Description>
+            )}
+            <FormField.Message messages={{ error: apiKeyFieldError }} />
+          </FormField>
+
+          {!isEdit && (isSubmitting || isConnected) && (
+            <Section
+              flexDirection="row"
+              alignItems="center"
+              justifyContent="start"
+              height="fit"
+              gap={1}
+              className="px-0.5"
+            >
+              <div className="p-0.5 shrink-0">
+                {isConnected ? (
+                  <SvgCheckCircle
+                    size={16}
+                    className="text-status-success-05"
+                  />
+                ) : (
+                  <SvgLoader size={16} className="animate-spin text-text-03" />
+                )}
+              </div>
+              <Text font="secondary-body" color="text-03">
+                {isConnected ? "Connection valid." : "Verifying connection…"}
+              </Text>
+            </Section>
+          )}
+        </Modal.Body>
+
+        <Modal.Footer>
+          <BasicModalFooter
+            cancel={
+              <Disabled disabled={isSubmitting}>
+                <Button
+                  prominence="secondary"
+                  onClick={() => handleOpenChange(false)}
+                >
+                  Cancel
+                </Button>
+              </Disabled>
+            }
+            submit={
+              <Disabled disabled={isSubmitting || !isValid || !hasChanges}>
+                <Button
+                  onClick={handleSubmit}
+                  icon={
+                    isSubmitting && !isEdit
+                      ? () => <SvgLoader size={16} className="animate-spin" />
+                      : undefined
+                  }
+                >
+                  {isEdit ? "Save Changes" : "Connect"}
+                </Button>
+              </Disabled>
+            }
+          />
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal>
+  );
+}

web/src/refresh-pages/admin/HooksPage/interfaces.ts

@@ -29,6 +29,14 @@ export interface HookResponse {
   updated_at: string;
 }
 
+export interface HookFormState {
+  name: string;
+  endpoint_url: string;
+  api_key: string;
+  fail_strategy: HookFailStrategy;
+  timeout_seconds: string;
+}
+
 export interface HookCreateRequest {
   name: string;
   hook_point: HookPoint;

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

@@ -5,15 +5,27 @@ import {
   HookValidateResponse,
 } from "@/refresh-pages/admin/HooksPage/interfaces";
 
-async function parseErrorDetail(
-  res: Response,
-  fallback: string
-): Promise<string> {
+export class HookAuthError extends Error {}
+export class HookTimeoutError extends Error {}
+export class HookConnectError extends Error {}
+
+async function parseError(res: Response, fallback: string): Promise<Error> {
   try {
     const body = await res.json();
-    return body?.detail ?? fallback;
+    if (body?.error_code === "CREDENTIAL_INVALID") {
+      return new HookAuthError(body?.detail ?? "Invalid API key.");
+    }
+    if (body?.error_code === "GATEWAY_TIMEOUT") {
+      return new HookTimeoutError(body?.detail ?? "Connection timed out.");
+    }
+    if (body?.error_code === "BAD_GATEWAY") {
+      return new HookConnectError(
+        body?.detail ?? "Could not connect to endpoint."
+      );
+    }
+    return new Error(body?.detail ?? fallback);
   } catch {
-    return fallback;
+    return new Error(fallback);
   }
 }
 
@@ -26,7 +38,7 @@ export async function createHook(
     body: JSON.stringify(req),
   });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to create hook"));
+    throw await parseError(res, "Failed to create hook");
   }
   return res.json();
 }
@@ -41,7 +53,7 @@ export async function updateHook(
     body: JSON.stringify(req),
   });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to update hook"));
+    throw await parseError(res, "Failed to update hook");
   }
   return res.json();
 }
@@ -49,7 +61,7 @@ export async function updateHook(
 export async function deleteHook(id: number): Promise<void> {
   const res = await fetch(`/api/admin/hooks/${id}`, { method: "DELETE" });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to delete hook"));
+    throw await parseError(res, "Failed to delete hook");
   }
 }
 
@@ -58,7 +70,7 @@ export async function activateHook(id: number): Promise<HookResponse> {
     method: "POST",
   });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to activate hook"));
+    throw await parseError(res, "Failed to activate hook");
   }
   return res.json();
 }
@@ -68,7 +80,7 @@ export async function deactivateHook(id: number): Promise<HookResponse> {
     method: "POST",
   });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to deactivate hook"));
+    throw await parseError(res, "Failed to deactivate hook");
   }
   return res.json();
 }
@@ -78,7 +90,7 @@ export async function validateHook(id: number): Promise<HookValidateResponse> {
     method: "POST",
   });
   if (!res.ok) {
-    throw new Error(await parseErrorDetail(res, "Failed to validate hook"));
+    throw await parseError(res, "Failed to validate hook");
   }
   return res.json();
 }

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

@@ -45,6 +45,7 @@ import OpenRouterModal from "@/sections/modals/llmConfig/OpenRouterModal";
 import CustomModal from "@/sections/modals/llmConfig/CustomModal";
 import LMStudioForm from "@/sections/modals/llmConfig/LMStudioForm";
 import LiteLLMProxyModal from "@/sections/modals/llmConfig/LiteLLMProxyModal";
+import BifrostModal from "@/sections/modals/llmConfig/BifrostModal";
 import { Section } from "@/layouts/general-layouts";
 
 const route = ADMIN_ROUTES.LLM_MODELS;
@@ -65,6 +66,7 @@ const PROVIDER_DISPLAY_ORDER: string[] = [
   "ollama_chat",
   "openrouter",
   "lm_studio",
+  "bifrost",
 ];
 
 const PROVIDER_MODAL_MAP: Record<
@@ -138,6 +140,13 @@ const PROVIDER_MODAL_MAP: Record<
       onOpenChange={onOpenChange}
     />
   ),
+  bifrost: (d, open, onOpenChange) => (
+    <BifrostModal
+      shouldMarkAsDefault={d}
+      open={open}
+      onOpenChange={onOpenChange}
+    />
+  ),
 };
 
 // ============================================================================

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import {
   AzureIcon,
   ElevenLabsIcon,
@@ -19,12 +19,18 @@ import {
 import {
   activateVoiceProvider,
   deactivateVoiceProvider,
+  deleteVoiceProvider,
 } from "@/lib/admin/voice/svc";
 import { ThreeDotsLoader } from "@/components/Loading";
+import { toast } from "@/hooks/useToast";
 import { Callout } from "@/components/ui/callout";
 import { Content } from "@opal/layouts";
-import { SvgMicrophone } from "@opal/icons";
+import { SvgMicrophone, SvgSlash, SvgUnplug } from "@opal/icons";
+import { Button as OpalButton } from "@opal/components";
+import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
+import { Section } from "@/layouts/general-layouts";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
 import VoiceProviderSetupModal from "@/app/admin/configuration/voice/VoiceProviderSetupModal";
 
 interface ModelDetails {
@@ -129,10 +135,152 @@ function getProviderIcon(
 
 type ProviderMode = "stt" | "tts";
 
+function getProviderLabel(providerType: string): string {
+  switch (providerType) {
+    case "openai":
+      return "OpenAI";
+    case "azure":
+      return "Azure";
+    case "elevenlabs":
+      return "ElevenLabs";
+    default:
+      return providerType;
+  }
+}
+
+const NO_DEFAULT_VALUE = "__none__";
+
 const route = ADMIN_ROUTES.VOICE;
 const pageDescription =
   "Configure speech-to-text and text-to-speech providers for voice input and spoken responses.";
 
+interface VoiceDisconnectModalProps {
+  disconnectTarget: {
+    providerId: number;
+    providerLabel: string;
+    providerType: string;
+  };
+  providers: VoiceProviderView[];
+  replacementProviderId: string | null;
+  onReplacementChange: (id: string | null) => void;
+  onClose: () => void;
+  onDisconnect: () => void;
+}
+
+function VoiceDisconnectModal({
+  disconnectTarget,
+  providers,
+  replacementProviderId,
+  onReplacementChange,
+  onClose,
+  onDisconnect,
+}: VoiceDisconnectModalProps) {
+  const targetProvider = providers.find(
+    (p) => p.id === disconnectTarget.providerId
+  );
+  const isActive =
+    (targetProvider?.is_default_stt ?? false) ||
+    (targetProvider?.is_default_tts ?? false);
+
+  // Find other configured providers that could serve as replacements
+  const replacementOptions = providers.filter(
+    (p) => p.id !== disconnectTarget.providerId && p.has_api_key
+  );
+
+  const needsReplacement = isActive;
+  const hasReplacements = replacementOptions.length > 0;
+
+  // Auto-select first replacement when modal opens
+  useEffect(() => {
+    if (needsReplacement && hasReplacements && !replacementProviderId) {
+      const first = replacementOptions[0];
+      if (first) onReplacementChange(String(first.id));
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <ConfirmationModalLayout
+      icon={SvgUnplug}
+      title={`Disconnect ${disconnectTarget.providerLabel}`}
+      description="Voice models"
+      onClose={onClose}
+      submit={
+        <OpalButton
+          variant="danger"
+          onClick={onDisconnect}
+          disabled={
+            needsReplacement && hasReplacements && !replacementProviderId
+          }
+        >
+          Disconnect
+        </OpalButton>
+      }
+    >
+      {needsReplacement ? (
+        hasReplacements ? (
+          <Section alignItems="start">
+            <Text as="p" text03>
+              <b>{disconnectTarget.providerLabel}</b> models will no longer be
+              used for speech-to-text or text-to-speech, and it will no longer
+              be your default. Session history will be preserved.
+            </Text>
+            <Section alignItems="start" gap={0.25}>
+              <Text as="p" text04>
+                Set New Default
+              </Text>
+              <InputSelect
+                value={replacementProviderId ?? undefined}
+                onValueChange={(v) => onReplacementChange(v)}
+              >
+                <InputSelect.Trigger placeholder="Select a replacement provider" />
+                <InputSelect.Content>
+                  {replacementOptions.map((p) => (
+                    <InputSelect.Item
+                      key={p.id}
+                      value={String(p.id)}
+                      icon={getProviderIcon(p.provider_type)}
+                    >
+                      {getProviderLabel(p.provider_type)}
+                    </InputSelect.Item>
+                  ))}
+                  <InputSelect.Separator />
+                  <InputSelect.Item value={NO_DEFAULT_VALUE} icon={SvgSlash}>
+                    <span>
+                      <b>No Default</b>
+                      <span className="text-text-03"> (Disable Voice)</span>
+                    </span>
+                  </InputSelect.Item>
+                </InputSelect.Content>
+              </InputSelect>
+            </Section>
+          </Section>
+        ) : (
+          <>
+            <Text as="p" text03>
+              <b>{disconnectTarget.providerLabel}</b> models will no longer be
+              used for speech-to-text or text-to-speech, and it will no longer
+              be your default.
+            </Text>
+            <Text as="p" text03>
+              Connect another provider to continue using voice.
+            </Text>
+          </>
+        )
+      ) : (
+        <>
+          <Text as="p" text03>
+            <b>{disconnectTarget.providerLabel}</b> models will no longer be
+            available for voice.
+          </Text>
+          <Text as="p" text03>
+            Session history will be preserved.
+          </Text>
+        </>
+      )}
+    </ConfirmationModalLayout>
+  );
+}
+
 export default function VoiceConfigurationPage() {
   const [modalOpen, setModalOpen] = useState(false);
   const [selectedProvider, setSelectedProvider] = useState<string | null>(null);
@@ -146,6 +294,14 @@ export default function VoiceConfigurationPage() {
   const [ttsActivationError, setTTSActivationError] = useState<string | null>(
     null
   );
+  const [disconnectTarget, setDisconnectTarget] = useState<{
+    providerId: number;
+    providerLabel: string;
+    providerType: string;
+  } | null>(null);
+  const [replacementProviderId, setReplacementProviderId] = useState<
+    string | null
+  >(null);
 
   const { providers, error, isLoading, refresh: mutate } = useVoiceProviders();
 
@@ -237,6 +393,65 @@ export default function VoiceConfigurationPage() {
     handleModalClose();
   };
 
+  const handleDisconnect = async () => {
+    if (!disconnectTarget) return;
+    try {
+      const targetProvider = providers.find(
+        (p) => p.id === disconnectTarget.providerId
+      );
+
+      // If a replacement was selected (not "No Default"), activate it for each
+      // mode the disconnected provider was default for
+      if (replacementProviderId && replacementProviderId !== NO_DEFAULT_VALUE) {
+        const repId = Number(replacementProviderId);
+
+        if (targetProvider?.is_default_stt) {
+          const resp = await activateVoiceProvider(repId, "stt");
+          if (!resp.ok) {
+            const errorBody = await resp.json().catch(() => ({}));
+            throw new Error(
+              typeof errorBody?.detail === "string"
+                ? errorBody.detail
+                : "Failed to activate replacement STT provider."
+            );
+          }
+        }
+
+        if (targetProvider?.is_default_tts) {
+          const resp = await activateVoiceProvider(repId, "tts");
+          if (!resp.ok) {
+            const errorBody = await resp.json().catch(() => ({}));
+            throw new Error(
+              typeof errorBody?.detail === "string"
+                ? errorBody.detail
+                : "Failed to activate replacement TTS provider."
+            );
+          }
+        }
+      }
+
+      const response = await deleteVoiceProvider(disconnectTarget.providerId);
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({}));
+        throw new Error(
+          typeof errorBody?.detail === "string"
+            ? errorBody.detail
+            : "Failed to disconnect provider."
+        );
+      }
+      await mutate();
+      toast.success(`${disconnectTarget.providerLabel} disconnected`);
+    } catch (err) {
+      console.error("Failed to disconnect voice provider:", err);
+      toast.error(
+        err instanceof Error ? err.message : "Unexpected error occurred."
+      );
+    } finally {
+      setDisconnectTarget(null);
+      setReplacementProviderId(null);
+    }
+  };
+
   const isProviderConfigured = (provider?: VoiceProviderView): boolean => {
     return !!provider?.has_api_key;
   };
@@ -289,6 +504,16 @@ export default function VoiceConfigurationPage() {
         onEdit={() => {
           if (provider) handleEdit(provider, mode, model.id);
         }}
+        onDisconnect={
+          status !== "disconnected" && provider
+            ? () =>
+                setDisconnectTarget({
+                  providerId: provider.id,
+                  providerLabel: getProviderLabel(model.providerType),
+                  providerType: model.providerType,
+                })
+            : undefined
+        }
       />
     );
   };
@@ -412,6 +637,20 @@ export default function VoiceConfigurationPage() {
         </div>
       </SettingsLayouts.Body>
 
+      {disconnectTarget && (
+        <VoiceDisconnectModal
+          disconnectTarget={disconnectTarget}
+          providers={providers}
+          replacementProviderId={replacementProviderId}
+          onReplacementChange={setReplacementProviderId}
+          onClose={() => {
+            setDisconnectTarget(null);
+            setReplacementProviderId(null);
+          }}
+          onDisconnect={() => void handleDisconnect()}
+        />
+      )}
+
       {modalOpen && selectedProvider && (
         <VoiceProviderSetupModal
           providerType={selectedProvider}