From 0c4fd30cceafaa9569909877de41339d32304b7b Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:12:57 +0530
Subject: [PATCH 01/28] feat: add unified HITL approval utility for sensitive
 tool actions

This new module provides a `request_approval()` function that streamlines the process of requesting user approval for sensitive actions, including decision parsing and parameter merging. It enhances the interaction with tools by allowing for user modifications and handling trusted tools seamlessly.
---
 .../app/agents/new_chat/chat_deepagent.py     |   2 +-
 .../app/agents/new_chat/tools/hitl.py         | 140 ++++++++++++++++++
 2 files changed, 141 insertions(+), 1 deletion(-)
 create mode 100644 surfsense_backend/app/agents/new_chat/tools/hitl.py

diff --git a/surfsense_backend/app/agents/new_chat/chat_deepagent.py b/surfsense_backend/app/agents/new_chat/chat_deepagent.py
index 6ff98badf..2b19a507e 100644
--- a/surfsense_backend/app/agents/new_chat/chat_deepagent.py
+++ b/surfsense_backend/app/agents/new_chat/chat_deepagent.py
@@ -470,7 +470,7 @@ async def create_surfsense_deep_agent(
         SubAgentMiddleware(backend=StateBackend, subagents=[general_purpose_spec]),
         create_summarization_middleware(llm, StateBackend),
         PatchToolCallsMiddleware(),
-        DedupHITLToolCallsMiddleware(),
+        DedupHITLToolCallsMiddleware(agent_tools=tools),
         AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
     ]
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/hitl.py b/surfsense_backend/app/agents/new_chat/tools/hitl.py
new file mode 100644
index 000000000..a1ac90dc7
--- /dev/null
+++ b/surfsense_backend/app/agents/new_chat/tools/hitl.py
@@ -0,0 +1,140 @@
+"""Unified HITL (Human-in-the-Loop) approval utility.
+
+Provides a single ``request_approval()`` function that encapsulates the
+interrupt payload creation, decision parsing, and parameter merging logic
+shared by every sensitive tool (native connectors and MCP tools alike).
+
+Usage inside a tool::
+
+    from app.agents.new_chat.tools.hitl import request_approval
+
+    result = request_approval(
+        action_type="gmail_email_send",
+        tool_name="send_gmail_email",
+        params={"to": to, "subject": subject, "body": body},
+        context=context,
+    )
+    if result.rejected:
+        return {"status": "rejected", "message": "User declined."}
+    # result.params contains the final (possibly edited) parameters
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from langgraph.types import interrupt
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class HITLResult:
+    """Outcome of a human-in-the-loop approval request."""
+
+    rejected: bool
+    decision_type: str
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+def _parse_decision(approval: Any) -> tuple[str, dict[str, Any]]:
+    """Extract the first valid decision and its edited parameters.
+
+    Returns:
+        (decision_type, edited_params) where *decision_type* is one of
+        ``"approve"``, ``"edit"``, or ``"reject"`` and *edited_params* is
+        the dict of user-modified arguments (empty when there are none).
+
+    Raises:
+        ValueError: when no usable decision dict can be found.
+    """
+    decisions_raw = approval.get("decisions", []) if isinstance(approval, dict) else []
+    decisions = decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
+    decisions = [d for d in decisions if isinstance(d, dict)]
+
+    if not decisions:
+        raise ValueError("No approval decision received")
+
+    decision = decisions[0]
+    decision_type: str = decision.get("type") or decision.get("decision_type") or "approve"
+
+    edited_params: dict[str, Any] = {}
+    edited_action = decision.get("edited_action")
+    if isinstance(edited_action, dict):
+        edited_args = edited_action.get("args")
+        if isinstance(edited_args, dict):
+            edited_params = edited_args
+    elif isinstance(decision.get("args"), dict):
+        edited_params = decision["args"]
+
+    return decision_type, edited_params
+
+
+def request_approval(
+    *,
+    action_type: str,
+    tool_name: str,
+    params: dict[str, Any],
+    context: dict[str, Any] | None = None,
+    trusted_tools: list[str] | None = None,
+) -> HITLResult:
+    """Pause the graph for user approval and return the decision.
+
+    This is a **synchronous** helper (not ``async``) because
+    ``langgraph.types.interrupt`` is itself synchronous — it raises a
+    ``GraphInterrupt`` exception that the LangGraph runtime catches.
+
+    Parameters
+    ----------
+    action_type:
+        A label that the frontend uses to select the correct approval card
+        (e.g. ``"gmail_email_send"``, ``"mcp_tool_call"``).
+    tool_name:
+        The registered LangChain tool name (e.g. ``"send_gmail_email"``).
+    params:
+        The original tool arguments.  These are shown in the approval card
+        and used as defaults when the user does not edit anything.
+    context:
+        Rich metadata from a ``*ToolMetadataService`` (accounts, folders,
+        labels, etc.).  For MCP tools this can hold the server name and
+        tool description.
+    trusted_tools:
+        An allow-list of tool names the user has previously marked as
+        "Always Allow".  If *tool_name* appears in this list, HITL is
+        skipped and the tool executes immediately.
+
+    Returns
+    -------
+    HITLResult
+        ``result.rejected`` is ``True`` when the user chose to deny the
+        action.  Otherwise ``result.params`` contains the final parameter
+        dict — either the originals or the user-edited version merged on
+        top.
+    """
+    if trusted_tools and tool_name in trusted_tools:
+        logger.info("Tool '%s' is user-trusted — skipping HITL", tool_name)
+        return HITLResult(rejected=False, decision_type="trusted", params=dict(params))
+
+    approval = interrupt(
+        {
+            "type": action_type,
+            "action": {"tool": tool_name, "params": params},
+            "context": context or {},
+        }
+    )
+
+    try:
+        decision_type, edited_params = _parse_decision(approval)
+    except ValueError:
+        logger.warning("No approval decision received for %s", tool_name)
+        return HITLResult(rejected=False, decision_type="error", params=params)
+
+    logger.info("User decision for %s: %s", tool_name, decision_type)
+
+    if decision_type == "reject":
+        return HITLResult(rejected=True, decision_type="reject", params=params)
+
+    final_params = {**params, **edited_params} if edited_params else dict(params)
+    return HITLResult(rejected=False, decision_type=decision_type, params=final_params)

From 82c7d4a2ab2589f0fa0ef48dde42c92c80721f35 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:14:12 +0530
Subject: [PATCH 02/28] refactor: enhance deduplication logic for HITL tool
 calls

Updated the deduplication mechanism in the DedupHITLToolCallsMiddleware to utilize a comprehensive list of native HITL tools. The deduplication keys are now dynamically populated from both hardcoded values and metadata from StructuredTool instances. Additionally, integrated HITL approval into MCP tool creation, ensuring all tools are gated by user approval, with the ability to bypass for trusted tools.
---
 .../new_chat/middleware/dedup_tool_calls.py   |  56 +++++-
 .../app/agents/new_chat/tools/mcp_tool.py     | 180 +++++++++---------
 2 files changed, 137 insertions(+), 99 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/middleware/dedup_tool_calls.py b/surfsense_backend/app/agents/new_chat/middleware/dedup_tool_calls.py
index f5e8f1235..bc6f7fd9e 100644
--- a/surfsense_backend/app/agents/new_chat/middleware/dedup_tool_calls.py
+++ b/surfsense_backend/app/agents/new_chat/middleware/dedup_tool_calls.py
@@ -20,19 +20,39 @@ from langgraph.runtime import Runtime
 
 logger = logging.getLogger(__name__)
 
-_HITL_TOOL_DEDUP_KEYS: dict[str, str] = {
-    "delete_calendar_event": "event_title_or_id",
-    "update_calendar_event": "event_title_or_id",
-    "trash_gmail_email": "email_subject_or_id",
+_NATIVE_HITL_TOOL_DEDUP_KEYS: dict[str, str] = {
+    # Gmail
+    "send_gmail_email": "subject",
+    "create_gmail_draft": "subject",
     "update_gmail_draft": "draft_subject_or_id",
+    "trash_gmail_email": "email_subject_or_id",
+    # Google Calendar
+    "create_calendar_event": "title",
+    "update_calendar_event": "event_title_or_id",
+    "delete_calendar_event": "event_title_or_id",
+    # Google Drive
+    "create_google_drive_file": "file_name",
     "delete_google_drive_file": "file_name",
+    # OneDrive
+    "create_onedrive_file": "file_name",
     "delete_onedrive_file": "file_name",
-    "delete_notion_page": "page_title",
+    # Dropbox
+    "create_dropbox_file": "file_name",
+    "delete_dropbox_file": "file_name",
+    # Notion
+    "create_notion_page": "title",
     "update_notion_page": "page_title",
-    "delete_linear_issue": "issue_ref",
+    "delete_notion_page": "page_title",
+    # Linear
+    "create_linear_issue": "title",
     "update_linear_issue": "issue_ref",
+    "delete_linear_issue": "issue_ref",
+    # Jira
+    "create_jira_issue": "summary",
     "update_jira_issue": "issue_title_or_key",
     "delete_jira_issue": "issue_title_or_key",
+    # Confluence
+    "create_confluence_page": "title",
     "update_confluence_page": "page_title_or_id",
     "delete_confluence_page": "page_title_or_id",
 }
@@ -43,22 +63,38 @@ class DedupHITLToolCallsMiddleware(AgentMiddleware):  # type: ignore[type-arg]
 
     Only the **first** occurrence of each (tool-name, primary-arg-value)
     pair is kept; subsequent duplicates are silently dropped.
+
+    The dedup map is built from two sources:
+
+    1. A comprehensive list of native HITL tools (hardcoded above).
+    2. Any ``StructuredTool`` instances passed via *agent_tools* whose
+       ``metadata`` contains ``{"hitl": True, "hitl_dedup_key": "..."}``.
+       This is how MCP tools automatically get dedup support.
     """
 
     tools = ()
 
+    def __init__(self, *, agent_tools: list[Any] | None = None) -> None:
+        self._dedup_keys: dict[str, str] = dict(_NATIVE_HITL_TOOL_DEDUP_KEYS)
+        for t in agent_tools or []:
+            meta = getattr(t, "metadata", None) or {}
+            if meta.get("hitl") and meta.get("hitl_dedup_key"):
+                self._dedup_keys[t.name] = meta["hitl_dedup_key"]
+
     def after_model(
         self, state: AgentState, runtime: Runtime[Any]
     ) -> dict[str, Any] | None:
-        return self._dedup(state)
+        return self._dedup(state, self._dedup_keys)
 
     async def aafter_model(
         self, state: AgentState, runtime: Runtime[Any]
     ) -> dict[str, Any] | None:
-        return self._dedup(state)
+        return self._dedup(state, self._dedup_keys)
 
     @staticmethod
-    def _dedup(state: AgentState) -> dict[str, Any] | None:  # type: ignore[type-arg]
+    def _dedup(
+        state: AgentState, dedup_keys: dict[str, str]  # type: ignore[type-arg]
+    ) -> dict[str, Any] | None:
         messages = state.get("messages")
         if not messages:
             return None
@@ -73,7 +109,7 @@ class DedupHITLToolCallsMiddleware(AgentMiddleware):  # type: ignore[type-arg]
 
         for tc in tool_calls:
             name = tc.get("name", "")
-            dedup_key_arg = _HITL_TOOL_DEDUP_KEYS.get(name)
+            dedup_key_arg = dedup_keys.get(name)
             if dedup_key_arg is not None:
                 arg_val = str(tc.get("args", {}).get(dedup_key_arg, "")).lower()
                 key = (name, arg_val)
diff --git a/surfsense_backend/app/agents/new_chat/tools/mcp_tool.py b/surfsense_backend/app/agents/new_chat/tools/mcp_tool.py
index 2fb7ffb06..9743d049d 100644
--- a/surfsense_backend/app/agents/new_chat/tools/mcp_tool.py
+++ b/surfsense_backend/app/agents/new_chat/tools/mcp_tool.py
@@ -7,7 +7,11 @@ Supports both transport types:
 - stdio: Local process-based MCP servers (command, args, env)
 - streamable-http/http/sse: Remote HTTP-based MCP servers (url, headers)
 
-This implements real MCP protocol support similar to Cursor's implementation.
+All MCP tools are unconditionally gated by HITL (Human-in-the-Loop) approval.
+Per the MCP spec: "Clients MUST consider tool annotations to be untrusted unless
+they come from trusted servers."  Users can bypass HITL for specific tools by
+clicking "Always Allow", which adds the tool name to the connector's
+``config.trusted_tools`` allow-list.
 """
 
 import logging
@@ -21,6 +25,7 @@ from pydantic import BaseModel, create_model
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.agents.new_chat.tools.mcp_client import MCPClient
 from app.db import SearchSourceConnector, SearchSourceConnectorType
 
@@ -49,27 +54,15 @@ def _create_dynamic_input_model_from_schema(
     tool_name: str,
     input_schema: dict[str, Any],
 ) -> type[BaseModel]:
-    """Create a Pydantic model from MCP tool's JSON schema.
-
-    Args:
-        tool_name: Name of the tool (used for model class name)
-        input_schema: JSON schema from MCP server
-
-    Returns:
-        Pydantic model class for tool input validation
-
-    """
+    """Create a Pydantic model from MCP tool's JSON schema."""
     properties = input_schema.get("properties", {})
     required_fields = input_schema.get("required", [])
 
-    # Build Pydantic field definitions
     field_definitions = {}
     for param_name, param_schema in properties.items():
         param_description = param_schema.get("description", "")
         is_required = param_name in required_fields
 
-        # Use Any type for complex schemas to preserve structure
-        # This allows the MCP server to do its own validation
         from typing import Any as AnyType
 
         from pydantic import Field
@@ -85,7 +78,6 @@ def _create_dynamic_input_model_from_schema(
                 Field(None, description=param_description),
             )
 
-    # Create dynamic model
     model_name = f"{tool_name.replace(' ', '').replace('-', '_')}Input"
     return create_model(model_name, **field_definitions)
 
@@ -93,55 +85,70 @@ def _create_dynamic_input_model_from_schema(
 async def _create_mcp_tool_from_definition_stdio(
     tool_def: dict[str, Any],
     mcp_client: MCPClient,
+    *,
+    connector_name: str = "",
+    connector_id: int | None = None,
+    trusted_tools: list[str] | None = None,
 ) -> StructuredTool:
     """Create a LangChain tool from an MCP tool definition (stdio transport).
 
-    Args:
-        tool_def: Tool definition from MCP server with name, description, input_schema
-        mcp_client: MCP client instance for calling the tool
-
-    Returns:
-        LangChain StructuredTool instance
-
+    All MCP tools are unconditionally wrapped with HITL approval.
+    ``request_approval()`` is called OUTSIDE the try/except so that
+    ``GraphInterrupt`` propagates cleanly to LangGraph.
     """
     tool_name = tool_def.get("name", "unnamed_tool")
     tool_description = tool_def.get("description", "No description provided")
     input_schema = tool_def.get("input_schema", {"type": "object", "properties": {}})
 
-    # Log the actual schema for debugging
     logger.info(f"MCP tool '{tool_name}' input schema: {input_schema}")
 
-    # Create dynamic input model from schema
     input_model = _create_dynamic_input_model_from_schema(tool_name, input_schema)
 
     async def mcp_tool_call(**kwargs) -> str:
         """Execute the MCP tool call via the client with retry support."""
         logger.info(f"MCP tool '{tool_name}' called with params: {kwargs}")
 
+        # HITL — OUTSIDE try/except so GraphInterrupt propagates to LangGraph
+        hitl_result = request_approval(
+            action_type="mcp_tool_call",
+            tool_name=tool_name,
+            params=kwargs,
+            context={
+                "mcp_server": connector_name,
+                "tool_description": tool_description,
+                "mcp_transport": "stdio",
+                "mcp_connector_id": connector_id,
+            },
+            trusted_tools=trusted_tools,
+        )
+        if hitl_result.rejected:
+            return "Tool call rejected by user."
+        call_kwargs = hitl_result.params
+
         try:
-            # Connect to server and call tool (connect has built-in retry logic)
             async with mcp_client.connect():
-                result = await mcp_client.call_tool(tool_name, kwargs)
+                result = await mcp_client.call_tool(tool_name, call_kwargs)
                 return str(result)
         except RuntimeError as e:
-            # Connection failures after all retries
             error_msg = f"MCP tool '{tool_name}' connection failed after retries: {e!s}"
             logger.error(error_msg)
             return f"Error: {error_msg}"
         except Exception as e:
-            # Tool execution or other errors
             error_msg = f"MCP tool '{tool_name}' execution failed: {e!s}"
             logger.exception(error_msg)
             return f"Error: {error_msg}"
 
-    # Create StructuredTool with response_format to preserve exact schema
     tool = StructuredTool(
         name=tool_name,
         description=tool_description,
         coroutine=mcp_tool_call,
         args_schema=input_model,
-        # Store the original MCP schema as metadata so we can access it later
-        metadata={"mcp_input_schema": input_schema, "mcp_transport": "stdio"},
+        metadata={
+            "mcp_input_schema": input_schema,
+            "mcp_transport": "stdio",
+            "hitl": True,
+            "hitl_dedup_key": next(iter(input_schema.get("required", [])), None),
+        },
     )
 
     logger.info(f"Created MCP tool (stdio): '{tool_name}'")
@@ -152,43 +159,54 @@ async def _create_mcp_tool_from_definition_http(
     tool_def: dict[str, Any],
     url: str,
     headers: dict[str, str],
+    *,
+    connector_name: str = "",
+    connector_id: int | None = None,
+    trusted_tools: list[str] | None = None,
 ) -> StructuredTool:
     """Create a LangChain tool from an MCP tool definition (HTTP transport).
 
-    Args:
-        tool_def: Tool definition from MCP server with name, description, input_schema
-        url: URL of the MCP server
-        headers: HTTP headers for authentication
-
-    Returns:
-        LangChain StructuredTool instance
-
+    All MCP tools are unconditionally wrapped with HITL approval.
+    ``request_approval()`` is called OUTSIDE the try/except so that
+    ``GraphInterrupt`` propagates cleanly to LangGraph.
     """
     tool_name = tool_def.get("name", "unnamed_tool")
     tool_description = tool_def.get("description", "No description provided")
     input_schema = tool_def.get("input_schema", {"type": "object", "properties": {}})
 
-    # Log the actual schema for debugging
     logger.info(f"MCP HTTP tool '{tool_name}' input schema: {input_schema}")
 
-    # Create dynamic input model from schema
     input_model = _create_dynamic_input_model_from_schema(tool_name, input_schema)
 
     async def mcp_http_tool_call(**kwargs) -> str:
         """Execute the MCP tool call via HTTP transport."""
         logger.info(f"MCP HTTP tool '{tool_name}' called with params: {kwargs}")
 
+        # HITL — OUTSIDE try/except so GraphInterrupt propagates to LangGraph
+        hitl_result = request_approval(
+            action_type="mcp_tool_call",
+            tool_name=tool_name,
+            params=kwargs,
+            context={
+                "mcp_server": connector_name,
+                "tool_description": tool_description,
+                "mcp_transport": "http",
+                "mcp_connector_id": connector_id,
+            },
+            trusted_tools=trusted_tools,
+        )
+        if hitl_result.rejected:
+            return "Tool call rejected by user."
+        call_kwargs = hitl_result.params
+
         try:
             async with (
                 streamablehttp_client(url, headers=headers) as (read, write, _),
                 ClientSession(read, write) as session,
             ):
                 await session.initialize()
+                response = await session.call_tool(tool_name, arguments=call_kwargs)
 
-                # Call the tool
-                response = await session.call_tool(tool_name, arguments=kwargs)
-
-                # Extract content from response
                 result = []
                 for content in response.content:
                     if hasattr(content, "text"):
@@ -209,7 +227,6 @@ async def _create_mcp_tool_from_definition_http(
             logger.exception(error_msg)
             return f"Error: {error_msg}"
 
-    # Create StructuredTool
     tool = StructuredTool(
         name=tool_name,
         description=tool_description,
@@ -219,6 +236,8 @@ async def _create_mcp_tool_from_definition_http(
             "mcp_input_schema": input_schema,
             "mcp_transport": "http",
             "mcp_url": url,
+            "hitl": True,
+            "hitl_dedup_key": next(iter(input_schema.get("required", [])), None),
         },
     )
 
@@ -230,20 +249,11 @@ async def _load_stdio_mcp_tools(
     connector_id: int,
     connector_name: str,
     server_config: dict[str, Any],
+    trusted_tools: list[str] | None = None,
 ) -> list[StructuredTool]:
-    """Load tools from a stdio-based MCP server.
-
-    Args:
-        connector_id: Connector ID for logging
-        connector_name: Connector name for logging
-        server_config: Server configuration with command, args, env
-
-    Returns:
-        List of tools from the MCP server
-    """
+    """Load tools from a stdio-based MCP server."""
     tools: list[StructuredTool] = []
 
-    # Validate required command field
     command = server_config.get("command")
     if not command or not isinstance(command, str):
         logger.warning(
@@ -251,7 +261,6 @@ async def _load_stdio_mcp_tools(
         )
         return tools
 
-    # Validate args field (must be list if present)
     args = server_config.get("args", [])
     if not isinstance(args, list):
         logger.warning(
@@ -259,7 +268,6 @@ async def _load_stdio_mcp_tools(
         )
         return tools
 
-    # Validate env field (must be dict if present)
     env = server_config.get("env", {})
     if not isinstance(env, dict):
         logger.warning(
@@ -267,10 +275,8 @@ async def _load_stdio_mcp_tools(
         )
         return tools
 
-    # Create MCP client
     mcp_client = MCPClient(command, args, env)
 
-    # Connect and discover tools
     async with mcp_client.connect():
         tool_definitions = await mcp_client.list_tools()
 
@@ -279,10 +285,15 @@ async def _load_stdio_mcp_tools(
             f"'{command}' (connector {connector_id})"
         )
 
-    # Create LangChain tools from definitions
     for tool_def in tool_definitions:
         try:
-            tool = await _create_mcp_tool_from_definition_stdio(tool_def, mcp_client)
+            tool = await _create_mcp_tool_from_definition_stdio(
+                tool_def,
+                mcp_client,
+                connector_name=connector_name,
+                connector_id=connector_id,
+                trusted_tools=trusted_tools,
+            )
             tools.append(tool)
         except Exception as e:
             logger.exception(
@@ -297,20 +308,11 @@ async def _load_http_mcp_tools(
     connector_id: int,
     connector_name: str,
     server_config: dict[str, Any],
+    trusted_tools: list[str] | None = None,
 ) -> list[StructuredTool]:
-    """Load tools from an HTTP-based MCP server.
-
-    Args:
-        connector_id: Connector ID for logging
-        connector_name: Connector name for logging
-        server_config: Server configuration with url, headers
-
-    Returns:
-        List of tools from the MCP server
-    """
+    """Load tools from an HTTP-based MCP server."""
     tools: list[StructuredTool] = []
 
-    # Validate required url field
     url = server_config.get("url")
     if not url or not isinstance(url, str):
         logger.warning(
@@ -318,7 +320,6 @@ async def _load_http_mcp_tools(
         )
         return tools
 
-    # Validate headers field (must be dict if present)
     headers = server_config.get("headers", {})
     if not isinstance(headers, dict):
         logger.warning(
@@ -326,7 +327,6 @@ async def _load_http_mcp_tools(
         )
         return tools
 
-    # Connect and discover tools via HTTP
     try:
         async with (
             streamablehttp_client(url, headers=headers) as (read, write, _),
@@ -334,7 +334,6 @@ async def _load_http_mcp_tools(
         ):
             await session.initialize()
 
-            # List available tools
             response = await session.list_tools()
             tool_definitions = []
             for tool in response.tools:
@@ -353,11 +352,15 @@ async def _load_http_mcp_tools(
                 f"'{url}' (connector {connector_id})"
             )
 
-        # Create LangChain tools from definitions
         for tool_def in tool_definitions:
             try:
                 tool = await _create_mcp_tool_from_definition_http(
-                    tool_def, url, headers
+                    tool_def,
+                    url,
+                    headers,
+                    connector_name=connector_name,
+                    connector_id=connector_id,
+                    trusted_tools=trusted_tools,
                 )
                 tools.append(tool)
             except Exception as e:
@@ -398,14 +401,6 @@ async def load_mcp_tools(
 
     Results are cached per search space for up to 5 minutes to avoid
     re-spawning MCP server processes on every chat message.
-
-    Args:
-        session: Database session
-        search_space_id: User's search space ID
-
-    Returns:
-        List of LangChain StructuredTool instances
-
     """
     _evict_expired_mcp_cache()
 
@@ -436,6 +431,7 @@ async def load_mcp_tools(
             try:
                 config = connector.config or {}
                 server_config = config.get("server_config", {})
+                trusted_tools = config.get("trusted_tools", [])
 
                 if not server_config or not isinstance(server_config, dict):
                     logger.warning(
@@ -447,11 +443,17 @@ async def load_mcp_tools(
 
                 if transport in ("streamable-http", "http", "sse"):
                     connector_tools = await _load_http_mcp_tools(
-                        connector.id, connector.name, server_config
+                        connector.id,
+                        connector.name,
+                        server_config,
+                        trusted_tools=trusted_tools,
                     )
                 else:
                     connector_tools = await _load_stdio_mcp_tools(
-                        connector.id, connector.name, server_config
+                        connector.id,
+                        connector.name,
+                        server_config,
+                        trusted_tools=trusted_tools,
                     )
 
                 tools.extend(connector_tools)

From 3eb448ec8dc3a788ba431cce84c7f97b78341c11 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:14:50 +0530
Subject: [PATCH 03/28] refactor: replace interrupt calls with unified
 request_approval utility in Confluence and Dropbox tools

Updated the create, delete, and update functions in Confluence and Dropbox tools to utilize the new request_approval utility for handling user approvals. This change enhances code consistency and simplifies decision handling by merging parameters directly from the approval response.
---
 .../new_chat/tools/confluence/create_page.py  | 60 +++++-----------
 .../new_chat/tools/confluence/delete_page.py  | 56 ++++-----------
 .../new_chat/tools/confluence/update_page.py  | 68 ++++++-------------
 .../new_chat/tools/dropbox/create_file.py     | 64 ++++++-----------
 .../new_chat/tools/dropbox/trash_file.py      | 57 ++++------------
 5 files changed, 87 insertions(+), 218 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/tools/confluence/create_page.py b/surfsense_backend/app/agents/new_chat/tools/confluence/create_page.py
index b4d532b76..b76f4d757 100644
--- a/surfsense_backend/app/agents/new_chat/tools/confluence/create_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/confluence/create_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -65,54 +65,28 @@ def create_create_confluence_page_tool(
                     "connector_type": "confluence",
                 }
 
-            approval = interrupt(
-                {
-                    "type": "confluence_page_creation",
-                    "action": {
-                        "tool": "create_confluence_page",
-                        "params": {
-                            "title": title,
-                            "content": content,
-                            "space_id": space_id,
-                            "connector_id": connector_id,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="confluence_page_creation",
+                tool_name="create_confluence_page",
+                params={
+                    "title": title,
+                    "content": content,
+                    "space_id": space_id,
+                    "connector_id": connector_id,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not created.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_title = final_params.get("title", title)
-            final_content = final_params.get("content", content) or ""
-            final_space_id = final_params.get("space_id", space_id)
-            final_connector_id = final_params.get("connector_id", connector_id)
+            final_title = result.params.get("title", title)
+            final_content = result.params.get("content", content) or ""
+            final_space_id = result.params.get("space_id", space_id)
+            final_connector_id = result.params.get("connector_id", connector_id)
 
             if not final_title or not final_title.strip():
                 return {"status": "error", "message": "Page title cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/confluence/delete_page.py b/surfsense_backend/app/agents/new_chat/tools/confluence/delete_page.py
index ba1dae653..070efaf57 100644
--- a/surfsense_backend/app/agents/new_chat/tools/confluence/delete_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/confluence/delete_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -74,54 +74,28 @@ def create_delete_confluence_page_tool(
             document_id = page_data["document_id"]
             connector_id_from_context = context.get("account", {}).get("id")
 
-            approval = interrupt(
-                {
-                    "type": "confluence_page_deletion",
-                    "action": {
-                        "tool": "delete_confluence_page",
-                        "params": {
-                            "page_id": page_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="confluence_page_deletion",
+                tool_name="delete_confluence_page",
+                params={
+                    "page_id": page_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not deleted.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_page_id = final_params.get("page_id", page_id)
-            final_connector_id = final_params.get(
+            final_page_id = result.params.get("page_id", page_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/confluence/update_page.py b/surfsense_backend/app/agents/new_chat/tools/confluence/update_page.py
index 913896f83..c80df9710 100644
--- a/surfsense_backend/app/agents/new_chat/tools/confluence/update_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/confluence/update_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -78,62 +78,36 @@ def create_update_confluence_page_tool(
             document_id = page_data.get("document_id")
             connector_id_from_context = context.get("account", {}).get("id")
 
-            approval = interrupt(
-                {
-                    "type": "confluence_page_update",
-                    "action": {
-                        "tool": "update_confluence_page",
-                        "params": {
-                            "page_id": page_id,
-                            "document_id": document_id,
-                            "new_title": new_title,
-                            "new_content": new_content,
-                            "version": current_version,
-                            "connector_id": connector_id_from_context,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="confluence_page_update",
+                tool_name="update_confluence_page",
+                params={
+                    "page_id": page_id,
+                    "document_id": document_id,
+                    "new_title": new_title,
+                    "new_content": new_content,
+                    "version": current_version,
+                    "connector_id": connector_id_from_context,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not updated.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_page_id = final_params.get("page_id", page_id)
-            final_title = final_params.get("new_title", new_title) or current_title
-            final_content = final_params.get("new_content", new_content)
+            final_page_id = result.params.get("page_id", page_id)
+            final_title = result.params.get("new_title", new_title) or current_title
+            final_content = result.params.get("new_content", new_content)
             if final_content is None:
                 final_content = current_body
-            final_version = final_params.get("version", current_version)
-            final_connector_id = final_params.get(
+            final_version = result.params.get("version", current_version)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_document_id = final_params.get("document_id", document_id)
+            final_document_id = result.params.get("document_id", document_id)
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/dropbox/create_file.py b/surfsense_backend/app/agents/new_chat/tools/dropbox/create_file.py
index ed8034861..6e2578334 100644
--- a/surfsense_backend/app/agents/new_chat/tools/dropbox/create_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/dropbox/create_file.py
@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
@@ -159,56 +159,30 @@ def create_create_dropbox_file_tool(
                 "supported_types": _SUPPORTED_TYPES,
             }
 
-            approval = interrupt(
-                {
-                    "type": "dropbox_file_creation",
-                    "action": {
-                        "tool": "create_dropbox_file",
-                        "params": {
-                            "name": name,
-                            "file_type": file_type,
-                            "content": content,
-                            "connector_id": None,
-                            "parent_folder_path": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="dropbox_file_creation",
+                tool_name="create_dropbox_file",
+                params={
+                    "name": name,
+                    "file_type": file_type,
+                    "content": content,
+                    "connector_id": None,
+                    "parent_folder_path": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The file was not created.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_name = final_params.get("name", name)
-            final_file_type = final_params.get("file_type", file_type)
-            final_content = final_params.get("content", content)
-            final_connector_id = final_params.get("connector_id")
-            final_parent_folder_path = final_params.get("parent_folder_path")
+            final_name = result.params.get("name", name)
+            final_file_type = result.params.get("file_type", file_type)
+            final_content = result.params.get("content", content)
+            final_connector_id = result.params.get("connector_id")
+            final_parent_folder_path = result.params.get("parent_folder_path")
 
             if not final_name or not final_name.strip():
                 return {"status": "error", "message": "File name cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/dropbox/trash_file.py b/surfsense_backend/app/agents/new_chat/tools/dropbox/trash_file.py
index e15dc3092..620b39aa2 100644
--- a/surfsense_backend/app/agents/new_chat/tools/dropbox/trash_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/dropbox/trash_file.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy import String, and_, cast, func
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
@@ -174,53 +174,26 @@ def create_delete_dropbox_file_tool(
                 },
             }
 
-            approval = interrupt(
-                {
-                    "type": "dropbox_file_trash",
-                    "action": {
-                        "tool": "delete_dropbox_file",
-                        "params": {
-                            "file_path": file_path,
-                            "connector_id": connector.id,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="dropbox_file_trash",
+                tool_name="delete_dropbox_file",
+                params={
+                    "file_path": file_path,
+                    "connector_id": connector.id,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The file was not deleted. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_file_path = final_params.get("file_path", file_path)
-            final_connector_id = final_params.get("connector_id", connector.id)
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_file_path = result.params.get("file_path", file_path)
+            final_connector_id = result.params.get("connector_id", connector.id)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             if final_connector_id != connector.id:
                 result = await db_session.execute(

From 85baaacd0a8a02369fb85cf76d9036b34c8f5fc5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:15:31 +0530
Subject: [PATCH 04/28] refactor: replace interrupt calls with request_approval
 utility in Gmail tools

Updated the create, send, update, and trash functions in Gmail tools to utilize the new request_approval utility for handling user approvals. This change improves code consistency and simplifies decision handling by directly merging parameters from the approval response.
---
 .../new_chat/tools/gmail/create_draft.py      | 68 +++++------------
 .../agents/new_chat/tools/gmail/send_email.py | 68 +++++------------
 .../new_chat/tools/gmail/trash_email.py       | 56 ++++----------
 .../new_chat/tools/gmail/update_draft.py      | 74 ++++++-------------
 4 files changed, 77 insertions(+), 189 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/tools/gmail/create_draft.py b/surfsense_backend/app/agents/new_chat/tools/gmail/create_draft.py
index a812f621a..974f9b4af 100644
--- a/surfsense_backend/app/agents/new_chat/tools/gmail/create_draft.py
+++ b/surfsense_backend/app/agents/new_chat/tools/gmail/create_draft.py
@@ -6,7 +6,7 @@ from email.mime.text import MIMEText
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.services.gmail import GmailToolMetadataService
@@ -85,60 +85,32 @@ def create_create_gmail_draft_tool(
             logger.info(
                 f"Requesting approval for creating Gmail draft: to='{to}', subject='{subject}'"
             )
-            approval = interrupt(
-                {
-                    "type": "gmail_draft_creation",
-                    "action": {
-                        "tool": "create_gmail_draft",
-                        "params": {
-                            "to": to,
-                            "subject": subject,
-                            "body": body,
-                            "cc": cc,
-                            "bcc": bcc,
-                            "connector_id": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="gmail_draft_creation",
+                tool_name="create_gmail_draft",
+                params={
+                    "to": to,
+                    "subject": subject,
+                    "body": body,
+                    "cc": cc,
+                    "bcc": bcc,
+                    "connector_id": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The draft was not created. Do not ask again or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_to = final_params.get("to", to)
-            final_subject = final_params.get("subject", subject)
-            final_body = final_params.get("body", body)
-            final_cc = final_params.get("cc", cc)
-            final_bcc = final_params.get("bcc", bcc)
-            final_connector_id = final_params.get("connector_id")
+            final_to = result.params.get("to", to)
+            final_subject = result.params.get("subject", subject)
+            final_body = result.params.get("body", body)
+            final_cc = result.params.get("cc", cc)
+            final_bcc = result.params.get("bcc", bcc)
+            final_connector_id = result.params.get("connector_id")
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/gmail/send_email.py b/surfsense_backend/app/agents/new_chat/tools/gmail/send_email.py
index 2599578bd..a1c713f0a 100644
--- a/surfsense_backend/app/agents/new_chat/tools/gmail/send_email.py
+++ b/surfsense_backend/app/agents/new_chat/tools/gmail/send_email.py
@@ -6,7 +6,7 @@ from email.mime.text import MIMEText
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.services.gmail import GmailToolMetadataService
@@ -86,60 +86,32 @@ def create_send_gmail_email_tool(
             logger.info(
                 f"Requesting approval for sending Gmail email: to='{to}', subject='{subject}'"
             )
-            approval = interrupt(
-                {
-                    "type": "gmail_email_send",
-                    "action": {
-                        "tool": "send_gmail_email",
-                        "params": {
-                            "to": to,
-                            "subject": subject,
-                            "body": body,
-                            "cc": cc,
-                            "bcc": bcc,
-                            "connector_id": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="gmail_email_send",
+                tool_name="send_gmail_email",
+                params={
+                    "to": to,
+                    "subject": subject,
+                    "body": body,
+                    "cc": cc,
+                    "bcc": bcc,
+                    "connector_id": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The email was not sent. Do not ask again or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_to = final_params.get("to", to)
-            final_subject = final_params.get("subject", subject)
-            final_body = final_params.get("body", body)
-            final_cc = final_params.get("cc", cc)
-            final_bcc = final_params.get("bcc", bcc)
-            final_connector_id = final_params.get("connector_id")
+            final_to = result.params.get("to", to)
+            final_subject = result.params.get("subject", subject)
+            final_body = result.params.get("body", body)
+            final_cc = result.params.get("cc", cc)
+            final_bcc = result.params.get("bcc", bcc)
+            final_connector_id = result.params.get("connector_id")
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/gmail/trash_email.py b/surfsense_backend/app/agents/new_chat/tools/gmail/trash_email.py
index 146020845..cab97ee8a 100644
--- a/surfsense_backend/app/agents/new_chat/tools/gmail/trash_email.py
+++ b/surfsense_backend/app/agents/new_chat/tools/gmail/trash_email.py
@@ -4,7 +4,7 @@ from datetime import datetime
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.services.gmail import GmailToolMetadataService
@@ -101,56 +101,28 @@ def create_trash_gmail_email_tool(
             logger.info(
                 f"Requesting approval for trashing Gmail email: '{email_subject_or_id}' (message_id={message_id}, delete_from_kb={delete_from_kb})"
             )
-            approval = interrupt(
-                {
-                    "type": "gmail_email_trash",
-                    "action": {
-                        "tool": "trash_gmail_email",
-                        "params": {
-                            "message_id": message_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="gmail_email_trash",
+                tool_name="trash_gmail_email",
+                params={
+                    "message_id": message_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The email was not trashed. Do not ask again or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_message_id = final_params.get("message_id", message_id)
-            final_connector_id = final_params.get(
+            final_message_id = result.params.get("message_id", message_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             if not final_connector_id:
                 return {
diff --git a/surfsense_backend/app/agents/new_chat/tools/gmail/update_draft.py b/surfsense_backend/app/agents/new_chat/tools/gmail/update_draft.py
index 28deec2b4..1d53ac9ce 100644
--- a/surfsense_backend/app/agents/new_chat/tools/gmail/update_draft.py
+++ b/surfsense_backend/app/agents/new_chat/tools/gmail/update_draft.py
@@ -6,7 +6,7 @@ from email.mime.text import MIMEText
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.services.gmail import GmailToolMetadataService
@@ -122,65 +122,37 @@ def create_update_gmail_draft_tool(
                 f"Requesting approval for updating Gmail draft: '{original_subject}' "
                 f"(message_id={message_id}, draft_id={draft_id_from_context})"
             )
-            approval = interrupt(
-                {
-                    "type": "gmail_draft_update",
-                    "action": {
-                        "tool": "update_gmail_draft",
-                        "params": {
-                            "message_id": message_id,
-                            "draft_id": draft_id_from_context,
-                            "to": final_to_default,
-                            "subject": final_subject_default,
-                            "body": body,
-                            "cc": cc,
-                            "bcc": bcc,
-                            "connector_id": connector_id_from_context,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="gmail_draft_update",
+                tool_name="update_gmail_draft",
+                params={
+                    "message_id": message_id,
+                    "draft_id": draft_id_from_context,
+                    "to": final_to_default,
+                    "subject": final_subject_default,
+                    "body": body,
+                    "cc": cc,
+                    "bcc": bcc,
+                    "connector_id": connector_id_from_context,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The draft was not updated. Do not ask again or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_to = final_params.get("to", final_to_default)
-            final_subject = final_params.get("subject", final_subject_default)
-            final_body = final_params.get("body", body)
-            final_cc = final_params.get("cc", cc)
-            final_bcc = final_params.get("bcc", bcc)
-            final_connector_id = final_params.get(
+            final_to = result.params.get("to", final_to_default)
+            final_subject = result.params.get("subject", final_subject_default)
+            final_body = result.params.get("body", body)
+            final_cc = result.params.get("cc", cc)
+            final_bcc = result.params.get("bcc", bcc)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_draft_id = final_params.get("draft_id", draft_id_from_context)
+            final_draft_id = result.params.get("draft_id", draft_id_from_context)
 
             if not final_connector_id:
                 return {

From 2f59fc9c725f1502020dce85c05fef50d7c6fb45 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:16:09 +0530
Subject: [PATCH 05/28] refactor: replace interrupt calls with request_approval
 utility in Google Calendar and Drive tools

Updated the create, delete, and update functions in Google Calendar and Google Drive tools to utilize the new request_approval utility for handling user approvals. This change enhances code consistency and simplifies decision handling by directly merging parameters from the approval response.
---
 .../tools/google_calendar/create_event.py     | 74 ++++++------------
 .../tools/google_calendar/delete_event.py     | 56 ++++---------
 .../tools/google_calendar/update_event.py     | 78 ++++++-------------
 .../tools/google_drive/create_file.py         | 64 +++++----------
 .../new_chat/tools/google_drive/trash_file.py | 56 ++++---------
 5 files changed, 94 insertions(+), 234 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/tools/google_calendar/create_event.py b/surfsense_backend/app/agents/new_chat/tools/google_calendar/create_event.py
index 592ced5ec..37bcf083e 100644
--- a/surfsense_backend/app/agents/new_chat/tools/google_calendar/create_event.py
+++ b/surfsense_backend/app/agents/new_chat/tools/google_calendar/create_event.py
@@ -6,9 +6,9 @@ from typing import Any
 from google.oauth2.credentials import Credentials
 from googleapiclient.discovery import build
 from langchain_core.tools import tool
-from langgraph.types import interrupt
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)
@@ -90,63 +90,35 @@ def create_create_calendar_event_tool(
             logger.info(
                 f"Requesting approval for creating calendar event: summary='{summary}'"
             )
-            approval = interrupt(
-                {
-                    "type": "google_calendar_event_creation",
-                    "action": {
-                        "tool": "create_calendar_event",
-                        "params": {
-                            "summary": summary,
-                            "start_datetime": start_datetime,
-                            "end_datetime": end_datetime,
-                            "description": description,
-                            "location": location,
-                            "attendees": attendees,
-                            "timezone": context.get("timezone"),
-                            "connector_id": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="google_calendar_event_creation",
+                tool_name="create_calendar_event",
+                params={
+                    "summary": summary,
+                    "start_datetime": start_datetime,
+                    "end_datetime": end_datetime,
+                    "description": description,
+                    "location": location,
+                    "attendees": attendees,
+                    "timezone": context.get("timezone"),
+                    "connector_id": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The event was not created. Do not ask again or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_summary = final_params.get("summary", summary)
-            final_start_datetime = final_params.get("start_datetime", start_datetime)
-            final_end_datetime = final_params.get("end_datetime", end_datetime)
-            final_description = final_params.get("description", description)
-            final_location = final_params.get("location", location)
-            final_attendees = final_params.get("attendees", attendees)
-            final_connector_id = final_params.get("connector_id")
+            final_summary = result.params.get("summary", summary)
+            final_start_datetime = result.params.get("start_datetime", start_datetime)
+            final_end_datetime = result.params.get("end_datetime", end_datetime)
+            final_description = result.params.get("description", description)
+            final_location = result.params.get("location", location)
+            final_attendees = result.params.get("attendees", attendees)
+            final_connector_id = result.params.get("connector_id")
 
             if not final_summary or not final_summary.strip():
                 return {"status": "error", "message": "Event summary cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/google_calendar/delete_event.py b/surfsense_backend/app/agents/new_chat/tools/google_calendar/delete_event.py
index 8b088487c..4d9d69b4b 100644
--- a/surfsense_backend/app/agents/new_chat/tools/google_calendar/delete_event.py
+++ b/surfsense_backend/app/agents/new_chat/tools/google_calendar/delete_event.py
@@ -6,9 +6,9 @@ from typing import Any
 from google.oauth2.credentials import Credentials
 from googleapiclient.discovery import build
 from langchain_core.tools import tool
-from langgraph.types import interrupt
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)
@@ -100,56 +100,28 @@ def create_delete_calendar_event_tool(
             logger.info(
                 f"Requesting approval for deleting calendar event: '{event_title_or_id}' (event_id={event_id}, delete_from_kb={delete_from_kb})"
             )
-            approval = interrupt(
-                {
-                    "type": "google_calendar_event_deletion",
-                    "action": {
-                        "tool": "delete_calendar_event",
-                        "params": {
-                            "event_id": event_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="google_calendar_event_deletion",
+                tool_name="delete_calendar_event",
+                params={
+                    "event_id": event_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The event was not deleted. Do not ask again or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_event_id = final_params.get("event_id", event_id)
-            final_connector_id = final_params.get(
+            final_event_id = result.params.get("event_id", event_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             if not final_connector_id:
                 return {
diff --git a/surfsense_backend/app/agents/new_chat/tools/google_calendar/update_event.py b/surfsense_backend/app/agents/new_chat/tools/google_calendar/update_event.py
index ed826f1b8..45ff6dfb9 100644
--- a/surfsense_backend/app/agents/new_chat/tools/google_calendar/update_event.py
+++ b/surfsense_backend/app/agents/new_chat/tools/google_calendar/update_event.py
@@ -6,9 +6,9 @@ from typing import Any
 from google.oauth2.credentials import Credentials
 from googleapiclient.discovery import build
 from langchain_core.tools import tool
-from langgraph.types import interrupt
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)
@@ -116,71 +116,43 @@ def create_update_calendar_event_tool(
             logger.info(
                 f"Requesting approval for updating calendar event: '{event_title_or_id}' (event_id={event_id})"
             )
-            approval = interrupt(
-                {
-                    "type": "google_calendar_event_update",
-                    "action": {
-                        "tool": "update_calendar_event",
-                        "params": {
-                            "event_id": event_id,
-                            "document_id": document_id,
-                            "connector_id": connector_id_from_context,
-                            "new_summary": new_summary,
-                            "new_start_datetime": new_start_datetime,
-                            "new_end_datetime": new_end_datetime,
-                            "new_description": new_description,
-                            "new_location": new_location,
-                            "new_attendees": new_attendees,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="google_calendar_event_update",
+                tool_name="update_calendar_event",
+                params={
+                    "event_id": event_id,
+                    "document_id": document_id,
+                    "connector_id": connector_id_from_context,
+                    "new_summary": new_summary,
+                    "new_start_datetime": new_start_datetime,
+                    "new_end_datetime": new_end_datetime,
+                    "new_description": new_description,
+                    "new_location": new_location,
+                    "new_attendees": new_attendees,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The event was not updated. Do not ask again or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_event_id = final_params.get("event_id", event_id)
-            final_connector_id = final_params.get(
+            final_event_id = result.params.get("event_id", event_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_new_summary = final_params.get("new_summary", new_summary)
-            final_new_start_datetime = final_params.get(
+            final_new_summary = result.params.get("new_summary", new_summary)
+            final_new_start_datetime = result.params.get(
                 "new_start_datetime", new_start_datetime
             )
-            final_new_end_datetime = final_params.get(
+            final_new_end_datetime = result.params.get(
                 "new_end_datetime", new_end_datetime
             )
-            final_new_description = final_params.get("new_description", new_description)
-            final_new_location = final_params.get("new_location", new_location)
-            final_new_attendees = final_params.get("new_attendees", new_attendees)
+            final_new_description = result.params.get("new_description", new_description)
+            final_new_location = result.params.get("new_location", new_location)
+            final_new_attendees = result.params.get("new_attendees", new_attendees)
 
             if not final_connector_id:
                 return {
diff --git a/surfsense_backend/app/agents/new_chat/tools/google_drive/create_file.py b/surfsense_backend/app/agents/new_chat/tools/google_drive/create_file.py
index a4fee0965..f36db8f3f 100644
--- a/surfsense_backend/app/agents/new_chat/tools/google_drive/create_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/google_drive/create_file.py
@@ -3,9 +3,9 @@ from typing import Any, Literal
 
 from googleapiclient.errors import HttpError
 from langchain_core.tools import tool
-from langgraph.types import interrupt
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.connectors.google_drive.client import GoogleDriveClient
 from app.connectors.google_drive.file_types import GOOGLE_DOC, GOOGLE_SHEET
 from app.services.google_drive import GoogleDriveToolMetadataService
@@ -99,58 +99,30 @@ def create_create_google_drive_file_tool(
             logger.info(
                 f"Requesting approval for creating Google Drive file: name='{name}', type='{file_type}'"
             )
-            approval = interrupt(
-                {
-                    "type": "google_drive_file_creation",
-                    "action": {
-                        "tool": "create_google_drive_file",
-                        "params": {
-                            "name": name,
-                            "file_type": file_type,
-                            "content": content,
-                            "connector_id": None,
-                            "parent_folder_id": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="google_drive_file_creation",
+                tool_name="create_google_drive_file",
+                params={
+                    "name": name,
+                    "file_type": file_type,
+                    "content": content,
+                    "connector_id": None,
+                    "parent_folder_id": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The file was not created. Do not ask again or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_name = final_params.get("name", name)
-            final_file_type = final_params.get("file_type", file_type)
-            final_content = final_params.get("content", content)
-            final_connector_id = final_params.get("connector_id")
-            final_parent_folder_id = final_params.get("parent_folder_id")
+            final_name = result.params.get("name", name)
+            final_file_type = result.params.get("file_type", file_type)
+            final_content = result.params.get("content", content)
+            final_connector_id = result.params.get("connector_id")
+            final_parent_folder_id = result.params.get("parent_folder_id")
 
             if not final_name or not final_name.strip():
                 return {"status": "error", "message": "File name cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/google_drive/trash_file.py b/surfsense_backend/app/agents/new_chat/tools/google_drive/trash_file.py
index fdf7f9cd3..832afff0d 100644
--- a/surfsense_backend/app/agents/new_chat/tools/google_drive/trash_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/google_drive/trash_file.py
@@ -3,9 +3,9 @@ from typing import Any
 
 from googleapiclient.errors import HttpError
 from langchain_core.tools import tool
-from langgraph.types import interrupt
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.new_chat.tools.hitl import request_approval
 from app.connectors.google_drive.client import GoogleDriveClient
 from app.services.google_drive import GoogleDriveToolMetadataService
 
@@ -101,56 +101,28 @@ def create_delete_google_drive_file_tool(
             logger.info(
                 f"Requesting approval for deleting Google Drive file: '{file_name}' (file_id={file_id}, delete_from_kb={delete_from_kb})"
             )
-            approval = interrupt(
-                {
-                    "type": "google_drive_file_trash",
-                    "action": {
-                        "tool": "delete_google_drive_file",
-                        "params": {
-                            "file_id": file_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="google_drive_file_trash",
+                tool_name="delete_google_drive_file",
+                params={
+                    "file_id": file_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
                     "message": "User declined. The file was not trashed. Do not ask again or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_file_id = final_params.get("file_id", file_id)
-            final_connector_id = final_params.get(
+            final_file_id = result.params.get("file_id", file_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             if not final_connector_id:
                 return {

From 4875fd9211afdb9a452bac99a7af640bb082e2d3 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:17:06 +0530
Subject: [PATCH 06/28] refactor: replace interrupt calls with request_approval
 utility in Jira and OneDrive tools

Updated the create, delete, and update functions in Jira and OneDrive tools to utilize the new request_approval utility for handling user approvals. This change improves code consistency and simplifies decision handling by directly merging parameters from the approval response.
---
 .../new_chat/tools/jira/create_issue.py       | 68 ++++++-------------
 .../new_chat/tools/jira/delete_issue.py       | 56 ++++-----------
 .../new_chat/tools/jira/update_issue.py       | 68 ++++++-------------
 .../new_chat/tools/onedrive/create_file.py    | 60 +++++-----------
 .../new_chat/tools/onedrive/trash_file.py     | 57 ++++------------
 5 files changed, 89 insertions(+), 220 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/tools/jira/create_issue.py b/surfsense_backend/app/agents/new_chat/tools/jira/create_issue.py
index d441c49f3..0b3332694 100644
--- a/surfsense_backend/app/agents/new_chat/tools/jira/create_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/jira/create_issue.py
@@ -3,7 +3,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -69,58 +69,32 @@ def create_create_jira_issue_tool(
                     "connector_type": "jira",
                 }
 
-            approval = interrupt(
-                {
-                    "type": "jira_issue_creation",
-                    "action": {
-                        "tool": "create_jira_issue",
-                        "params": {
-                            "project_key": project_key,
-                            "summary": summary,
-                            "issue_type": issue_type,
-                            "description": description,
-                            "priority": priority,
-                            "connector_id": connector_id,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="jira_issue_creation",
+                tool_name="create_jira_issue",
+                params={
+                    "project_key": project_key,
+                    "summary": summary,
+                    "issue_type": issue_type,
+                    "description": description,
+                    "priority": priority,
+                    "connector_id": connector_id,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not created.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_project_key = final_params.get("project_key", project_key)
-            final_summary = final_params.get("summary", summary)
-            final_issue_type = final_params.get("issue_type", issue_type)
-            final_description = final_params.get("description", description)
-            final_priority = final_params.get("priority", priority)
-            final_connector_id = final_params.get("connector_id", connector_id)
+            final_project_key = result.params.get("project_key", project_key)
+            final_summary = result.params.get("summary", summary)
+            final_issue_type = result.params.get("issue_type", issue_type)
+            final_description = result.params.get("description", description)
+            final_priority = result.params.get("priority", priority)
+            final_connector_id = result.params.get("connector_id", connector_id)
 
             if not final_summary or not final_summary.strip():
                 return {"status": "error", "message": "Issue summary cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/jira/delete_issue.py b/surfsense_backend/app/agents/new_chat/tools/jira/delete_issue.py
index 2f8c370ad..52d4556a5 100644
--- a/surfsense_backend/app/agents/new_chat/tools/jira/delete_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/jira/delete_issue.py
@@ -3,7 +3,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -71,54 +71,28 @@ def create_delete_jira_issue_tool(
             document_id = issue_data["document_id"]
             connector_id_from_context = context.get("account", {}).get("id")
 
-            approval = interrupt(
-                {
-                    "type": "jira_issue_deletion",
-                    "action": {
-                        "tool": "delete_jira_issue",
-                        "params": {
-                            "issue_key": issue_key,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="jira_issue_deletion",
+                tool_name="delete_jira_issue",
+                params={
+                    "issue_key": issue_key,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not deleted.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_issue_key = final_params.get("issue_key", issue_key)
-            final_connector_id = final_params.get(
+            final_issue_key = result.params.get("issue_key", issue_key)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py b/surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py
index c2b948ae3..9c676fea3 100644
--- a/surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py
@@ -3,7 +3,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
@@ -75,60 +75,34 @@ def create_update_jira_issue_tool(
             document_id = issue_data.get("document_id")
             connector_id_from_context = context.get("account", {}).get("id")
 
-            approval = interrupt(
-                {
-                    "type": "jira_issue_update",
-                    "action": {
-                        "tool": "update_jira_issue",
-                        "params": {
-                            "issue_key": issue_key,
-                            "document_id": document_id,
-                            "new_summary": new_summary,
-                            "new_description": new_description,
-                            "new_priority": new_priority,
-                            "connector_id": connector_id_from_context,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="jira_issue_update",
+                tool_name="update_jira_issue",
+                params={
+                    "issue_key": issue_key,
+                    "document_id": document_id,
+                    "new_summary": new_summary,
+                    "new_description": new_description,
+                    "new_priority": new_priority,
+                    "connector_id": connector_id_from_context,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not updated.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_issue_key = final_params.get("issue_key", issue_key)
-            final_summary = final_params.get("new_summary", new_summary)
-            final_description = final_params.get("new_description", new_description)
-            final_priority = final_params.get("new_priority", new_priority)
-            final_connector_id = final_params.get(
+            final_issue_key = result.params.get("issue_key", issue_key)
+            final_summary = result.params.get("new_summary", new_summary)
+            final_description = result.params.get("new_description", new_description)
+            final_priority = result.params.get("new_priority", new_priority)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_document_id = final_params.get("document_id", document_id)
+            final_document_id = result.params.get("document_id", document_id)
 
             from sqlalchemy.future import select
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/onedrive/create_file.py b/surfsense_backend/app/agents/new_chat/tools/onedrive/create_file.py
index 8dffb18dd..5050c7885 100644
--- a/surfsense_backend/app/agents/new_chat/tools/onedrive/create_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/onedrive/create_file.py
@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
@@ -145,54 +145,28 @@ def create_create_onedrive_file_tool(
                 "parent_folders": parent_folders,
             }
 
-            approval = interrupt(
-                {
-                    "type": "onedrive_file_creation",
-                    "action": {
-                        "tool": "create_onedrive_file",
-                        "params": {
-                            "name": name,
-                            "content": content,
-                            "connector_id": None,
-                            "parent_folder_id": None,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="onedrive_file_creation",
+                tool_name="create_onedrive_file",
+                params={
+                    "name": name,
+                    "content": content,
+                    "connector_id": None,
+                    "parent_folder_id": None,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The file was not created.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_name = final_params.get("name", name)
-            final_content = final_params.get("content", content)
-            final_connector_id = final_params.get("connector_id")
-            final_parent_folder_id = final_params.get("parent_folder_id")
+            final_name = result.params.get("name", name)
+            final_content = result.params.get("content", content)
+            final_connector_id = result.params.get("connector_id")
+            final_parent_folder_id = result.params.get("parent_folder_id")
 
             if not final_name or not final_name.strip():
                 return {"status": "error", "message": "File name cannot be empty."}
diff --git a/surfsense_backend/app/agents/new_chat/tools/onedrive/trash_file.py b/surfsense_backend/app/agents/new_chat/tools/onedrive/trash_file.py
index 79d8222fd..6997e1d52 100644
--- a/surfsense_backend/app/agents/new_chat/tools/onedrive/trash_file.py
+++ b/surfsense_backend/app/agents/new_chat/tools/onedrive/trash_file.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy import String, and_, cast, func
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
@@ -174,53 +174,26 @@ def create_delete_onedrive_file_tool(
                 },
             }
 
-            approval = interrupt(
-                {
-                    "type": "onedrive_file_trash",
-                    "action": {
-                        "tool": "delete_onedrive_file",
-                        "params": {
-                            "file_id": file_id,
-                            "connector_id": connector.id,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="onedrive_file_trash",
+                tool_name="delete_onedrive_file",
+                params={
+                    "file_id": file_id,
+                    "connector_id": connector.id,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 return {
                     "status": "rejected",
-                    "message": "User declined. The file was not trashed. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_file_id = final_params.get("file_id", file_id)
-            final_connector_id = final_params.get("connector_id", connector.id)
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_file_id = result.params.get("file_id", file_id)
+            final_connector_id = result.params.get("connector_id", connector.id)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             if final_connector_id != connector.id:
                 result = await db_session.execute(

From 8d8ba6cbe8a5f08044244e19569f312b76e3d4ba Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:17:36 +0530
Subject: [PATCH 07/28] refactor: replace interrupt calls with request_approval
 utility in Linear and Notion tools

Updated the create, delete, and update functions in Linear and Notion tools to utilize the new request_approval utility for handling user approvals. This change improves code consistency and simplifies decision handling by directly merging parameters from the approval response.
---
 .../new_chat/tools/linear/create_issue.py     | 78 ++++++------------
 .../new_chat/tools/linear/delete_issue.py     | 58 ++++---------
 .../new_chat/tools/linear/update_issue.py     | 82 ++++++-------------
 .../new_chat/tools/notion/create_page.py      | 66 ++++-----------
 .../new_chat/tools/notion/delete_page.py      | 64 ++++-----------
 .../new_chat/tools/notion/update_page.py      | 62 ++++----------
 6 files changed, 114 insertions(+), 296 deletions(-)

diff --git a/surfsense_backend/app/agents/new_chat/tools/linear/create_issue.py b/surfsense_backend/app/agents/new_chat/tools/linear/create_issue.py
index 2b5d37903..d8005bd5c 100644
--- a/surfsense_backend/app/agents/new_chat/tools/linear/create_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/linear/create_issue.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.linear_connector import LinearAPIError, LinearConnector
@@ -94,65 +94,37 @@ def create_create_linear_issue_tool(
                 }
 
             logger.info(f"Requesting approval for creating Linear issue: '{title}'")
-            approval = interrupt(
-                {
-                    "type": "linear_issue_creation",
-                    "action": {
-                        "tool": "create_linear_issue",
-                        "params": {
-                            "title": title,
-                            "description": description,
-                            "team_id": None,
-                            "state_id": None,
-                            "assignee_id": None,
-                            "priority": None,
-                            "label_ids": [],
-                            "connector_id": connector_id,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="linear_issue_creation",
+                tool_name="create_linear_issue",
+                params={
+                    "title": title,
+                    "description": description,
+                    "team_id": None,
+                    "state_id": None,
+                    "assignee_id": None,
+                    "priority": None,
+                    "label_ids": [],
+                    "connector_id": connector_id,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Linear issue creation rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not created. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            final_params: dict[str, Any] = {}
-            edited_action = decision.get("edited_action")
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_title = final_params.get("title", title)
-            final_description = final_params.get("description", description)
-            final_team_id = final_params.get("team_id")
-            final_state_id = final_params.get("state_id")
-            final_assignee_id = final_params.get("assignee_id")
-            final_priority = final_params.get("priority")
-            final_label_ids = final_params.get("label_ids") or []
-            final_connector_id = final_params.get("connector_id", connector_id)
+            final_title = result.params.get("title", title)
+            final_description = result.params.get("description", description)
+            final_team_id = result.params.get("team_id")
+            final_state_id = result.params.get("state_id")
+            final_assignee_id = result.params.get("assignee_id")
+            final_priority = result.params.get("priority")
+            final_label_ids = result.params.get("label_ids") or []
+            final_connector_id = result.params.get("connector_id", connector_id)
 
             if not final_title or not final_title.strip():
                 logger.error("Title is empty or contains only whitespace")
diff --git a/surfsense_backend/app/agents/new_chat/tools/linear/delete_issue.py b/surfsense_backend/app/agents/new_chat/tools/linear/delete_issue.py
index 9f4a60953..d8bc88d82 100644
--- a/surfsense_backend/app/agents/new_chat/tools/linear/delete_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/linear/delete_issue.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.linear_connector import LinearAPIError, LinearConnector
@@ -114,57 +114,29 @@ def create_delete_linear_issue_tool(
                 f"Requesting approval for deleting Linear issue: '{issue_ref}' "
                 f"(id={issue_id}, delete_from_kb={delete_from_kb})"
             )
-            approval = interrupt(
-                {
-                    "type": "linear_issue_deletion",
-                    "action": {
-                        "tool": "delete_linear_issue",
-                        "params": {
-                            "issue_id": issue_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="linear_issue_deletion",
+                tool_name="delete_linear_issue",
+                params={
+                    "issue_id": issue_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Linear issue deletion rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not deleted. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_issue_id = final_params.get("issue_id", issue_id)
-            final_connector_id = final_params.get(
+            final_issue_id = result.params.get("issue_id", issue_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             logger.info(
                 f"Deleting Linear issue with final params: issue_id={final_issue_id}, "
diff --git a/surfsense_backend/app/agents/new_chat/tools/linear/update_issue.py b/surfsense_backend/app/agents/new_chat/tools/linear/update_issue.py
index 19af851c1..7f6d952e5 100644
--- a/surfsense_backend/app/agents/new_chat/tools/linear/update_issue.py
+++ b/surfsense_backend/app/agents/new_chat/tools/linear/update_issue.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.linear_connector import LinearAPIError, LinearConnector
@@ -130,69 +130,41 @@ def create_update_linear_issue_tool(
             logger.info(
                 f"Requesting approval for updating Linear issue: '{issue_ref}' (id={issue_id})"
             )
-            approval = interrupt(
-                {
-                    "type": "linear_issue_update",
-                    "action": {
-                        "tool": "update_linear_issue",
-                        "params": {
-                            "issue_id": issue_id,
-                            "document_id": document_id,
-                            "new_title": new_title,
-                            "new_description": new_description,
-                            "new_state_id": new_state_id,
-                            "new_assignee_id": new_assignee_id,
-                            "new_priority": new_priority,
-                            "new_label_ids": new_label_ids,
-                            "connector_id": connector_id_from_context,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="linear_issue_update",
+                tool_name="update_linear_issue",
+                params={
+                    "issue_id": issue_id,
+                    "document_id": document_id,
+                    "new_title": new_title,
+                    "new_description": new_description,
+                    "new_state_id": new_state_id,
+                    "new_assignee_id": new_assignee_id,
+                    "new_priority": new_priority,
+                    "new_label_ids": new_label_ids,
+                    "connector_id": connector_id_from_context,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {"status": "error", "message": "No approval decision received"}
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Linear issue update rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The issue was not updated. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                final_params = decision["args"]
-
-            final_issue_id = final_params.get("issue_id", issue_id)
-            final_document_id = final_params.get("document_id", document_id)
-            final_new_title = final_params.get("new_title", new_title)
-            final_new_description = final_params.get("new_description", new_description)
-            final_new_state_id = final_params.get("new_state_id", new_state_id)
-            final_new_assignee_id = final_params.get("new_assignee_id", new_assignee_id)
-            final_new_priority = final_params.get("new_priority", new_priority)
-            final_new_label_ids: list[str] | None = final_params.get(
+            final_issue_id = result.params.get("issue_id", issue_id)
+            final_document_id = result.params.get("document_id", document_id)
+            final_new_title = result.params.get("new_title", new_title)
+            final_new_description = result.params.get("new_description", new_description)
+            final_new_state_id = result.params.get("new_state_id", new_state_id)
+            final_new_assignee_id = result.params.get("new_assignee_id", new_assignee_id)
+            final_new_priority = result.params.get("new_priority", new_priority)
+            final_new_label_ids: list[str] | None = result.params.get(
                 "new_label_ids", new_label_ids
             )
-            final_connector_id = final_params.get(
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
 
diff --git a/surfsense_backend/app/agents/new_chat/tools/notion/create_page.py b/surfsense_backend/app/agents/new_chat/tools/notion/create_page.py
index 5bb0c52d1..396f3fe0d 100644
--- a/surfsense_backend/app/agents/new_chat/tools/notion/create_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/notion/create_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
@@ -99,61 +99,29 @@ def create_create_notion_page_tool(
                 }
 
             logger.info(f"Requesting approval for creating Notion page: '{title}'")
-            approval = interrupt(
-                {
-                    "type": "notion_page_creation",
-                    "action": {
-                        "tool": "create_notion_page",
-                        "params": {
-                            "title": title,
-                            "content": content,
-                            "parent_page_id": None,
-                            "connector_id": connector_id,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="notion_page_creation",
+                tool_name="create_notion_page",
+                params={
+                    "title": title,
+                    "content": content,
+                    "parent_page_id": None,
+                    "connector_id": connector_id,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {
-                    "status": "error",
-                    "message": "No approval decision received",
-                }
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Notion page creation rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not created. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                # Some interrupt payloads place args directly on the decision.
-                final_params = decision["args"]
-
-            final_title = final_params.get("title", title)
-            final_content = final_params.get("content", content)
-            final_parent_page_id = final_params.get("parent_page_id")
-            final_connector_id = final_params.get("connector_id", connector_id)
+            final_title = result.params.get("title", title)
+            final_content = result.params.get("content", content)
+            final_parent_page_id = result.params.get("parent_page_id")
+            final_connector_id = result.params.get("connector_id", connector_id)
 
             if not final_title or not final_title.strip():
                 logger.error("Title is empty or contains only whitespace")
diff --git a/surfsense_backend/app/agents/new_chat/tools/notion/delete_page.py b/surfsense_backend/app/agents/new_chat/tools/notion/delete_page.py
index fbb7c5004..92e395624 100644
--- a/surfsense_backend/app/agents/new_chat/tools/notion/delete_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/notion/delete_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
@@ -114,63 +114,29 @@ def create_delete_notion_page_tool(
                 f"Requesting approval for deleting Notion page: '{page_title}' (page_id={page_id}, delete_from_kb={delete_from_kb})"
             )
 
-            # Request approval before deleting
-            approval = interrupt(
-                {
-                    "type": "notion_page_deletion",
-                    "action": {
-                        "tool": "delete_notion_page",
-                        "params": {
-                            "page_id": page_id,
-                            "connector_id": connector_id_from_context,
-                            "delete_from_kb": delete_from_kb,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="notion_page_deletion",
+                tool_name="delete_notion_page",
+                params={
+                    "page_id": page_id,
+                    "connector_id": connector_id_from_context,
+                    "delete_from_kb": delete_from_kb,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {
-                    "status": "error",
-                    "message": "No approval decision received",
-                }
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Notion page deletion rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not deleted. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            # Extract edited action arguments (if user modified the checkbox)
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                # Some interrupt payloads place args directly on the decision.
-                final_params = decision["args"]
-
-            final_page_id = final_params.get("page_id", page_id)
-            final_connector_id = final_params.get(
+            final_page_id = result.params.get("page_id", page_id)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
-            final_delete_from_kb = final_params.get("delete_from_kb", delete_from_kb)
+            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
 
             logger.info(
                 f"Deleting Notion page with final params: page_id={final_page_id}, connector_id={final_connector_id}, delete_from_kb={final_delete_from_kb}"
diff --git a/surfsense_backend/app/agents/new_chat/tools/notion/update_page.py b/surfsense_backend/app/agents/new_chat/tools/notion/update_page.py
index 25f2b9918..ee7b8f256 100644
--- a/surfsense_backend/app/agents/new_chat/tools/notion/update_page.py
+++ b/surfsense_backend/app/agents/new_chat/tools/notion/update_page.py
@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 from langchain_core.tools import tool
-from langgraph.types import interrupt
+from app.agents.new_chat.tools.hitl import request_approval
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
@@ -127,59 +127,27 @@ def create_update_notion_page_tool(
             logger.info(
                 f"Requesting approval for updating Notion page: '{page_title}' (page_id={page_id})"
             )
-            approval = interrupt(
-                {
-                    "type": "notion_page_update",
-                    "action": {
-                        "tool": "update_notion_page",
-                        "params": {
-                            "page_id": page_id,
-                            "content": content,
-                            "connector_id": connector_id_from_context,
-                        },
-                    },
-                    "context": context,
-                }
+            result = request_approval(
+                action_type="notion_page_update",
+                tool_name="update_notion_page",
+                params={
+                    "page_id": page_id,
+                    "content": content,
+                    "connector_id": connector_id_from_context,
+                },
+                context=context,
             )
 
-            decisions_raw = (
-                approval.get("decisions", []) if isinstance(approval, dict) else []
-            )
-            decisions = (
-                decisions_raw if isinstance(decisions_raw, list) else [decisions_raw]
-            )
-            decisions = [d for d in decisions if isinstance(d, dict)]
-            if not decisions:
-                logger.warning("No approval decision received")
-                return {
-                    "status": "error",
-                    "message": "No approval decision received",
-                }
-
-            decision = decisions[0]
-            decision_type = decision.get("type") or decision.get("decision_type")
-            logger.info(f"User decision: {decision_type}")
-
-            if decision_type == "reject":
+            if result.rejected:
                 logger.info("Notion page update rejected by user")
                 return {
                     "status": "rejected",
-                    "message": "User declined. The page was not updated. Do not ask again or suggest alternatives.",
+                    "message": "User declined. Do not retry or suggest alternatives.",
                 }
 
-            edited_action = decision.get("edited_action")
-            final_params: dict[str, Any] = {}
-            if isinstance(edited_action, dict):
-                edited_args = edited_action.get("args")
-                if isinstance(edited_args, dict):
-                    final_params = edited_args
-            elif isinstance(decision.get("args"), dict):
-                # Some interrupt payloads place args directly on the decision.
-                final_params = decision["args"]
-
-            final_page_id = final_params.get("page_id", page_id)
-            final_content = final_params.get("content", content)
-            final_connector_id = final_params.get(
+            final_page_id = result.params.get("page_id", page_id)
+            final_content = result.params.get("content", content)
+            final_connector_id = result.params.get(
                 "connector_id", connector_id_from_context
             )
 

From b3a8364fbd062b43ab759da3c040b139c863179d Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:18:12 +0530
Subject: [PATCH 08/28] feat: add MCP Tool Trust routes for managing trusted
 tools

---
 .../routes/search_source_connectors_routes.py | 111 ++++++++++++++++++
 1 file changed, 111 insertions(+)

diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index bb20da65d..ce19ab36d 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -3624,3 +3624,114 @@ async def get_drive_picker_token(
             status_code=500,
             detail="Failed to retrieve access token. Check server logs for details.",
         ) from e
+
+
+# =============================================================================
+# MCP Tool Trust (Allow-List) Routes
+# =============================================================================
+
+
+class MCPTrustToolRequest(BaseModel):
+    tool_name: str
+
+
+@router.post("/connectors/mcp/{connector_id}/trust-tool")
+async def trust_mcp_tool(
+    connector_id: int,
+    body: MCPTrustToolRequest,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Add a tool to the MCP connector's trusted (always-allow) list.
+
+    Once trusted, the tool executes without HITL approval on subsequent calls.
+    """
+    try:
+        result = await session.execute(
+            select(SearchSourceConnector).filter(
+                SearchSourceConnector.id == connector_id,
+                SearchSourceConnector.connector_type
+                == SearchSourceConnectorType.MCP_CONNECTOR,
+            )
+        )
+        connector = result.scalars().first()
+        if not connector:
+            raise HTTPException(status_code=404, detail="MCP connector not found")
+
+        config = dict(connector.config or {})
+        trusted: list[str] = list(config.get("trusted_tools", []))
+        if body.tool_name not in trusted:
+            trusted.append(body.tool_name)
+        config["trusted_tools"] = trusted
+        connector.config = config
+
+        from sqlalchemy.orm.attributes import flag_modified
+
+        flag_modified(connector, "config")
+        await session.commit()
+
+        from app.agents.new_chat.tools.mcp_tool import invalidate_mcp_tools_cache
+
+        invalidate_mcp_tools_cache(connector.search_space_id)
+
+        return {"status": "ok", "trusted_tools": trusted}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to trust MCP tool: {e!s}", exc_info=True)
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to trust tool: {e!s}"
+        ) from e
+
+
+@router.post("/connectors/mcp/{connector_id}/untrust-tool")
+async def untrust_mcp_tool(
+    connector_id: int,
+    body: MCPTrustToolRequest,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Remove a tool from the MCP connector's trusted list.
+
+    The tool will require HITL approval again on subsequent calls.
+    """
+    try:
+        result = await session.execute(
+            select(SearchSourceConnector).filter(
+                SearchSourceConnector.id == connector_id,
+                SearchSourceConnector.connector_type
+                == SearchSourceConnectorType.MCP_CONNECTOR,
+            )
+        )
+        connector = result.scalars().first()
+        if not connector:
+            raise HTTPException(status_code=404, detail="MCP connector not found")
+
+        config = dict(connector.config or {})
+        trusted: list[str] = list(config.get("trusted_tools", []))
+        if body.tool_name in trusted:
+            trusted.remove(body.tool_name)
+        config["trusted_tools"] = trusted
+        connector.config = config
+
+        from sqlalchemy.orm.attributes import flag_modified
+
+        flag_modified(connector, "config")
+        await session.commit()
+
+        from app.agents.new_chat.tools.mcp_tool import invalidate_mcp_tools_cache
+
+        invalidate_mcp_tools_cache(connector.search_space_id)
+
+        return {"status": "ok", "trusted_tools": trusted}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to untrust MCP tool: {e!s}", exc_info=True)
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to untrust tool: {e!s}"
+        ) from e

From ea7bcebcd05c7fb4cc2452d5b265934bd64db707 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:19:23 +0530
Subject: [PATCH 09/28] refactor: integrate HITL approval UI for interrupt
 results

Enhanced the NewChatPage to utilize the new GenericHitlApprovalToolUI for handling interrupt results. Updated the ToolFallback component to conditionally render the approval UI based on the result type. Additionally, introduced a new GenericHitlApprovalToolUI component to manage user approvals and parameter editing for tool actions.
---
 .../new-chat/[[...chat_id]]/page.tsx          |   4 +-
 .../components/assistant-ui/tool-fallback.tsx |  11 +-
 .../tool-ui/generic-hitl-approval.tsx         | 268 ++++++++++++++++++
 3 files changed, 280 insertions(+), 3 deletions(-)
 create mode 100644 surfsense_web/components/tool-ui/generic-hitl-approval.tsx

diff --git a/surfsense_web/app/dashboard/[search_space_id]/new-chat/[[...chat_id]]/page.tsx b/surfsense_web/app/dashboard/[search_space_id]/new-chat/[[...chat_id]]/page.tsx
index 0b1369340..58eb58f4b 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/new-chat/[[...chat_id]]/page.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/new-chat/[[...chat_id]]/page.tsx
@@ -798,7 +798,7 @@ export default function NewChatPage() {
 									});
 								} else {
 									const tcId = `interrupt-${action.name}`;
-									addToolCall(contentPartsState, TOOLS_WITH_UI, tcId, action.name, action.args);
+									addToolCall(contentPartsState, TOOLS_WITH_UI, tcId, action.name, action.args, true);
 									updateToolCall(contentPartsState, tcId, {
 										result: { __interrupt__: true, ...interruptData },
 									});
@@ -1125,7 +1125,7 @@ export default function NewChatPage() {
 									});
 								} else {
 									const tcId = `interrupt-${action.name}`;
-									addToolCall(contentPartsState, TOOLS_WITH_UI, tcId, action.name, action.args);
+									addToolCall(contentPartsState, TOOLS_WITH_UI, tcId, action.name, action.args, true);
 									updateToolCall(contentPartsState, tcId, {
 										result: {
 											__interrupt__: true,
diff --git a/surfsense_web/components/assistant-ui/tool-fallback.tsx b/surfsense_web/components/assistant-ui/tool-fallback.tsx
index b658dba6d..d9833b387 100644
--- a/surfsense_web/components/assistant-ui/tool-fallback.tsx
+++ b/surfsense_web/components/assistant-ui/tool-fallback.tsx
@@ -1,14 +1,16 @@
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { CheckIcon, ChevronDownIcon, ChevronUpIcon, XCircleIcon } from "lucide-react";
 import { useMemo, useState } from "react";
+import { GenericHitlApprovalToolUI } from "@/components/tool-ui/generic-hitl-approval";
 import { getToolIcon } from "@/contracts/enums/toolIcons";
+import { isInterruptResult } from "@/lib/hitl";
 import { cn } from "@/lib/utils";
 
 function formatToolName(name: string): string {
 	return name.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-export const ToolFallback: ToolCallMessagePartComponent = ({
+const DefaultToolFallbackInner: ToolCallMessagePartComponent = ({
 	toolName,
 	argsText,
 	result,
@@ -145,3 +147,10 @@ export const ToolFallback: ToolCallMessagePartComponent = ({
 		</div>
 	);
 };
+
+export const ToolFallback: ToolCallMessagePartComponent = (props) => {
+	if (isInterruptResult(props.result)) {
+		return <GenericHitlApprovalToolUI {...props} />;
+	}
+	return <DefaultToolFallbackInner {...props} />;
+};
diff --git a/surfsense_web/components/tool-ui/generic-hitl-approval.tsx b/surfsense_web/components/tool-ui/generic-hitl-approval.tsx
new file mode 100644
index 000000000..48d0d3764
--- /dev/null
+++ b/surfsense_web/components/tool-ui/generic-hitl-approval.tsx
@@ -0,0 +1,268 @@
+"use client";
+
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
+import { CornerDownLeftIcon, ShieldAlertIcon, ShieldCheckIcon } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { TextShimmerLoader } from "@/components/prompt-kit/loader";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { connectorsApiService } from "@/lib/apis/connectors-api.service";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
+
+function ParamEditor({
+	params,
+	onChange,
+	disabled,
+}: {
+	params: Record<string, unknown>;
+	onChange: (updated: Record<string, unknown>) => void;
+	disabled: boolean;
+}) {
+	const entries = Object.entries(params);
+	if (entries.length === 0) return null;
+
+	return (
+		<div className="space-y-2">
+			{entries.map(([key, value]) => {
+				const strValue = value == null ? "" : String(value);
+				const isLong = strValue.length > 120;
+				const fieldId = `hitl-param-${key}`;
+
+				return (
+					<div key={key} className="space-y-1">
+						<label htmlFor={fieldId} className="text-xs font-medium text-muted-foreground">
+							{key}
+						</label>
+						{isLong ? (
+							<Textarea
+								id={fieldId}
+								value={strValue}
+								disabled={disabled}
+								rows={3}
+								onChange={(e) => onChange({ ...params, [key]: e.target.value })}
+								className="text-xs"
+							/>
+						) : (
+							<Input
+								id={fieldId}
+								value={strValue}
+								disabled={disabled}
+								onChange={(e) => onChange({ ...params, [key]: e.target.value })}
+								className="text-xs"
+							/>
+						)}
+					</div>
+				);
+			})}
+		</div>
+	);
+}
+
+function GenericApprovalCard({
+	toolName,
+	args,
+	interruptData,
+	onDecision,
+}: {
+	toolName: string;
+	args: Record<string, unknown>;
+	interruptData: InterruptResult;
+	onDecision: (decision: HitlDecision) => void;
+}) {
+	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
+	const [editedParams, setEditedParams] = useState<Record<string, unknown>>(args);
+	const [isEditing, setIsEditing] = useState(false);
+
+	const displayName = toolName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+	const mcpServer = interruptData.context?.mcp_server as string | undefined;
+	const toolDescription = interruptData.context?.tool_description as string | undefined;
+	const mcpConnectorId = interruptData.context?.mcp_connector_id as number | undefined;
+	const isMCPTool = mcpConnectorId != null;
+
+	const reviewConfig = interruptData.review_configs?.[0];
+	const allowedDecisions = reviewConfig?.allowed_decisions ?? ["approve", "reject"];
+	const canEdit = allowedDecisions.includes("edit");
+
+	const hasChanged = useMemo(() => {
+		return JSON.stringify(editedParams) !== JSON.stringify(args);
+	}, [editedParams, args]);
+
+	const handleApprove = useCallback(() => {
+		if (phase !== "pending") return;
+		const isEdited = isEditing && hasChanged;
+		setProcessing();
+		onDecision({
+			type: isEdited ? "edit" : "approve",
+			edited_action: isEdited
+				? { name: interruptData.action_requests[0]?.name ?? toolName, args: editedParams }
+				: undefined,
+		});
+	}, [
+		phase,
+		setProcessing,
+		isEditing,
+		hasChanged,
+		onDecision,
+		interruptData,
+		toolName,
+		editedParams,
+	]);
+
+	const handleAlwaysAllow = useCallback(() => {
+		if (phase !== "pending" || !isMCPTool) return;
+		setProcessing();
+		onDecision({ type: "approve" });
+		connectorsApiService.trustMCPTool(mcpConnectorId, toolName).catch((err) => {
+			console.error("Failed to trust MCP tool:", err);
+		});
+	}, [phase, setProcessing, onDecision, isMCPTool, mcpConnectorId, toolName]);
+
+	useEffect(() => {
+		const handler = (e: KeyboardEvent) => {
+			if (e.key === "Enter" && !e.shiftKey && !e.ctrlKey && !e.metaKey && phase === "pending") {
+				handleApprove();
+			}
+		};
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, [handleApprove, phase]);
+
+	return (
+		<div className="my-4 max-w-lg overflow-hidden rounded-2xl border bg-muted/30 transition-[box-shadow] duration-300">
+			{/* Header */}
+			<div className="flex items-start gap-3 px-5 pt-5 pb-4 select-none">
+				<div className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-amber-500/10">
+					<ShieldAlertIcon className="size-4 text-amber-600" />
+				</div>
+				<div className="flex-1 min-w-0">
+					<p className="text-sm font-semibold text-foreground">
+						{phase === "rejected"
+							? `${displayName} — Rejected`
+							: phase === "processing" || phase === "complete"
+								? `${displayName} — Approved`
+								: `Approve: ${displayName}`}
+					</p>
+					{phase === "processing" ? (
+						<TextShimmerLoader text="Executing..." size="sm" />
+					) : phase === "complete" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">Action completed</p>
+					) : phase === "rejected" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">Action was cancelled</p>
+					) : (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							Requires your approval to proceed
+						</p>
+					)}
+					{mcpServer && (
+						<p className="text-[10px] text-muted-foreground/70 mt-1">
+							via <span className="font-medium">{mcpServer}</span>
+						</p>
+					)}
+				</div>
+			</div>
+
+			{/* Description */}
+			{toolDescription && phase === "pending" && (
+				<>
+					<div className="mx-5 h-px bg-border/50" />
+					<div className="px-5 py-2">
+						<p className="text-xs text-muted-foreground">{toolDescription}</p>
+					</div>
+				</>
+			)}
+
+			{/* Parameters */}
+			{Object.keys(args).length > 0 && (
+				<>
+					<div className="mx-5 h-px bg-border/50" />
+					<div className="px-5 py-3 space-y-2">
+						<p className="text-xs font-medium text-muted-foreground">Parameters</p>
+						{phase === "pending" && isEditing ? (
+							<ParamEditor
+								params={editedParams}
+								onChange={setEditedParams}
+								disabled={phase !== "pending"}
+							/>
+						) : (
+							<pre className="text-xs text-foreground/80 whitespace-pre-wrap break-all bg-muted/50 rounded-lg p-3">
+								{JSON.stringify(args, null, 2)}
+							</pre>
+						)}
+					</div>
+				</>
+			)}
+
+			{/* Action buttons */}
+			{phase === "pending" && (
+				<>
+					<div className="mx-5 h-px bg-border/50" />
+					<div className="px-5 py-3 flex items-center gap-2 select-none flex-wrap">
+						{allowedDecisions.includes("approve") && (
+							<Button size="sm" className="rounded-lg gap-1.5" onClick={handleApprove}>
+								{isEditing && hasChanged ? "Approve with edits" : "Approve"}
+								<CornerDownLeftIcon className="size-3 opacity-60" />
+							</Button>
+						)}
+						{isMCPTool && (
+							<Button
+								size="sm"
+								variant="outline"
+								className="rounded-lg gap-1.5"
+								onClick={handleAlwaysAllow}
+							>
+								<ShieldCheckIcon className="size-3" />
+								Always Allow
+							</Button>
+						)}
+						{canEdit && !isEditing && (
+							<Button
+								size="sm"
+								variant="outline"
+								className="rounded-lg"
+								onClick={() => setIsEditing(true)}
+							>
+								Edit
+							</Button>
+						)}
+						{allowedDecisions.includes("reject") && (
+							<Button
+								size="sm"
+								variant="ghost"
+								className="rounded-lg text-muted-foreground"
+								onClick={() => {
+									setRejected();
+									onDecision({ type: "reject", message: "User rejected the action." });
+								}}
+							>
+								Reject
+							</Button>
+						)}
+					</div>
+				</>
+			)}
+		</div>
+	);
+}
+
+export const GenericHitlApprovalToolUI: ToolCallMessagePartComponent = ({
+	toolName,
+	args,
+	result,
+}) => {
+	const { dispatch } = useHitlDecision();
+
+	if (!result || !isInterruptResult(result)) return null;
+
+	return (
+		<GenericApprovalCard
+			toolName={toolName}
+			args={args as Record<string, unknown>}
+			interruptData={result}
+			onDecision={(decision) => dispatch([decision])}
+		/>
+	);
+};

From f844c3288cdc6e3827618516d6436ed08ee28377 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:20:38 +0530
Subject: [PATCH 10/28] refactor: unify interrupt handling in Confluence and
 Jira tools

Refactored the create, delete, and update functions in Confluence and Jira tools to utilize a consistent InterruptResult interface with specific context types. This change enhances code clarity and maintains uniformity in handling user approvals across different tools by integrating the useHitlDecision hook for decision dispatching.
---
 .../confluence/create-confluence-page.tsx     | 53 ++++---------
 .../confluence/delete-confluence-page.tsx     | 74 ++++++------------
 .../confluence/update-confluence-page.tsx     | 75 ++++++-------------
 .../tool-ui/jira/create-jira-issue.tsx        | 57 ++++----------
 .../tool-ui/jira/delete-jira-issue.tsx        | 54 ++++---------
 .../tool-ui/jira/update-jira-issue.tsx        | 55 ++++----------
 6 files changed, 102 insertions(+), 266 deletions(-)

diff --git a/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
index d22f317b8..b60817536 100644
--- a/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
@@ -15,6 +15,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface ConfluenceAccount {
@@ -30,24 +32,10 @@ interface ConfluenceSpace {
 	name: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		accounts?: ConfluenceAccount[];
-		spaces?: ConfluenceSpace[];
-		error?: string;
-	};
+interface CreateConfluencePageInterruptContext {
+	accounts?: ConfluenceAccount[];
+	spaces?: ConfluenceSpace[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -76,21 +64,12 @@ interface InsufficientPermissionsResult {
 }
 
 type CreateConfluencePageResult =
-	| InterruptResult
+	| InterruptResult<CreateConfluencePageInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -124,12 +103,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { title: string; content?: string; space_id?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<CreateConfluencePageInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -464,18 +439,16 @@ export const CreateConfluencePageToolUI = ({
 	{ title: string; content?: string; space_id?: string },
 	CreateConfluencePageResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<CreateConfluencePageInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
index 258f259f0..ca45e26ee 100644
--- a/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
@@ -6,38 +6,26 @@ import { useCallback, useEffect, useState } from "react";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
+interface DeleteConfluencePageInterruptContext {
+	account?: {
+		id: number;
 		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		account?: {
-			id: number;
-			name: string;
-			base_url: string;
-			auth_expired?: boolean;
-		};
-		page?: {
-			page_id: string;
-			page_title: string;
-			space_id: string;
-			connector_id?: number;
-			document_id?: number;
-			indexed_at?: string;
-		};
-		error?: string;
+		base_url: string;
+		auth_expired?: boolean;
 	};
+	page?: {
+		page_id: string;
+		page_title: string;
+		space_id: string;
+		connector_id?: number;
+		document_id?: number;
+		indexed_at?: string;
+	};
+	error?: string;
 }
 
 interface SuccessResult {
@@ -77,7 +65,7 @@ interface InsufficientPermissionsResult {
 }
 
 type DeleteConfluencePageResult =
-	| InterruptResult
+	| InterruptResult<DeleteConfluencePageInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
@@ -85,15 +73,6 @@ type DeleteConfluencePageResult =
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -145,12 +124,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DeleteConfluencePageInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -402,18 +377,15 @@ export const DeleteConfluencePageToolUI = ({
 	{ page_title_or_id: string; delete_from_kb?: boolean },
 	DeleteConfluencePageResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<DeleteConfluencePageInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
index 8bc0772a4..7f75f9ac8 100644
--- a/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
@@ -8,39 +8,27 @@ import { openHitlEditPanelAtom } from "@/atoms/chat/hitl-edit-panel.atom";
 import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
+interface UpdateConfluencePageInterruptContext {
+	account?: {
+		id: number;
 		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		account?: {
-			id: number;
-			name: string;
-			base_url: string;
-			auth_expired?: boolean;
-		};
-		page?: {
-			page_id: string;
-			page_title: string;
-			space_id: string;
-			body: string;
-			version: number;
-			document_id: number;
-			indexed_at?: string;
-		};
-		error?: string;
+		base_url: string;
+		auth_expired?: boolean;
 	};
+	page?: {
+		page_id: string;
+		page_title: string;
+		space_id: string;
+		body: string;
+		version: number;
+		document_id: number;
+		indexed_at?: string;
+	};
+	error?: string;
 }
 
 interface SuccessResult {
@@ -74,22 +62,13 @@ interface InsufficientPermissionsResult {
 }
 
 type UpdateConfluencePageResult =
-	| InterruptResult
+	| InterruptResult<UpdateConfluencePageInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -136,12 +115,8 @@ function ApprovalCard({
 		new_title?: string;
 		new_content?: string;
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<UpdateConfluencePageInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 
@@ -502,18 +477,16 @@ export const UpdateConfluencePageToolUI = ({
 	},
 	UpdateConfluencePageResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<UpdateConfluencePageInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
index cabb0d840..4561cd9dd 100644
--- a/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
@@ -15,6 +15,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface JiraAccount {
@@ -40,26 +42,12 @@ interface JiraPriority {
 	name: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		accounts?: JiraAccount[];
-		projects?: JiraProject[];
-		issue_types?: JiraIssueType[];
-		priorities?: JiraPriority[];
-		error?: string;
-	};
+interface CreateJiraIssueInterruptContext {
+	accounts?: JiraAccount[];
+	projects?: JiraProject[];
+	issue_types?: JiraIssueType[];
+	priorities?: JiraPriority[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -88,21 +76,12 @@ interface InsufficientPermissionsResult {
 }
 
 type CreateJiraIssueResult =
-	| InterruptResult
+	| InterruptResult<CreateJiraIssueInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -142,12 +121,8 @@ function ApprovalCard({
 		description?: string;
 		priority?: string;
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<CreateJiraIssueInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -549,18 +524,16 @@ export const CreateJiraIssueToolUI = ({
 	},
 	CreateJiraIssueResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<CreateJiraIssueInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
index 2cad2be46..cb8da37ea 100644
--- a/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
@@ -6,6 +6,8 @@ import { useCallback, useEffect, useState } from "react";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface JiraAccount {
@@ -23,24 +25,10 @@ interface JiraIssue {
 	document_id?: number;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		account?: JiraAccount;
-		issue?: JiraIssue;
-		error?: string;
-	};
+interface DeleteJiraIssueInterruptContext {
+	account?: JiraAccount;
+	issue?: JiraIssue;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -79,7 +67,7 @@ interface InsufficientPermissionsResult {
 }
 
 type DeleteJiraIssueResult =
-	| InterruptResult
+	| InterruptResult<DeleteJiraIssueInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
@@ -87,15 +75,6 @@ type DeleteJiraIssueResult =
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -147,12 +126,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DeleteJiraIssueInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -399,18 +374,15 @@ export const DeleteJiraIssueToolUI = ({
 	{ issue_title_or_key: string; delete_from_kb?: boolean },
 	DeleteJiraIssueResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<DeleteJiraIssueInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
index 4132fad06..24643b542 100644
--- a/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
@@ -16,6 +16,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface JiraIssue {
@@ -43,25 +45,11 @@ interface JiraPriority {
 	name: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		account?: JiraAccount;
-		issue?: JiraIssue;
-		priorities?: JiraPriority[];
-		error?: string;
-	};
+interface UpdateJiraIssueInterruptContext {
+	account?: JiraAccount;
+	issue?: JiraIssue;
+	priorities?: JiraPriority[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -95,22 +83,13 @@ interface InsufficientPermissionsResult {
 }
 
 type UpdateJiraIssueResult =
-	| InterruptResult
+	| InterruptResult<UpdateJiraIssueInterruptContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| AuthErrorResult
 	| InsufficientPermissionsResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -158,12 +137,8 @@ function ApprovalCard({
 		new_description?: string;
 		new_priority?: string;
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<UpdateJiraIssueInterruptContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 
@@ -563,18 +538,16 @@ export const UpdateJiraIssueToolUI = ({
 	},
 	UpdateJiraIssueResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<UpdateJiraIssueInterruptContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}

From 71cd04b05ec443e637a5c880bc4dd4eb6a2c9065 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:21:16 +0530
Subject: [PATCH 11/28] refactor: unify interrupt handling in Dropbox and
 Google Drive tools

Refactored the create and delete file functionalities in Dropbox and Google Drive tools to utilize a consistent InterruptResult interface with specific context types. This change enhances code clarity and maintains uniformity in handling user approvals by integrating the useHitlDecision hook for decision dispatching.
---
 .../tool-ui/dropbox/create-file.tsx           | 50 +++++------------
 .../components/tool-ui/dropbox/trash-file.tsx | 40 +++++---------
 .../tool-ui/google-drive/create-file.tsx      | 53 +++++--------------
 .../tool-ui/google-drive/trash-file.tsx       | 52 +++++-------------
 4 files changed, 50 insertions(+), 145 deletions(-)

diff --git a/surfsense_web/components/tool-ui/dropbox/create-file.tsx b/surfsense_web/components/tool-ui/dropbox/create-file.tsx
index ac45f1f5b..70daf491c 100644
--- a/surfsense_web/components/tool-ui/dropbox/create-file.tsx
+++ b/surfsense_web/components/tool-ui/dropbox/create-file.tsx
@@ -16,6 +16,8 @@ import {
 	SelectValue,
 } from "@/components/ui/select";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface DropboxAccount {
 	id: number;
@@ -29,21 +31,11 @@ interface SupportedType {
 	label: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{ name: string; args: Record<string, unknown> }>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: DropboxAccount[];
-		parent_folders?: Record<number, Array<{ folder_path: string; name: string }>>;
-		supported_types?: SupportedType[];
-		error?: string;
-	};
+interface DropboxCreateFileContext {
+	accounts?: DropboxAccount[];
+	parent_folders?: Record<number, Array<{ folder_path: string; name: string }>>;
+	supported_types?: SupportedType[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -65,16 +57,7 @@ interface AuthErrorResult {
 	connector_type?: string;
 }
 
-type CreateDropboxFileResult = InterruptResult | SuccessResult | ErrorResult | AuthErrorResult;
-
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
+type CreateDropboxFileResult = InterruptResult<DropboxCreateFileContext> | SuccessResult | ErrorResult | AuthErrorResult;
 
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
@@ -100,12 +83,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { name: string; file_type?: string; content?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DropboxCreateFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -455,17 +434,14 @@ export const CreateDropboxFileToolUI = ({
 	{ name: string; file_type?: string; content?: string },
 	CreateDropboxFileResult
 >) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<DropboxCreateFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/dropbox/trash-file.tsx b/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
index 0b38777c1..3d4ad8a94 100644
--- a/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
@@ -7,6 +7,8 @@ import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface DropboxAccount {
 	id: number;
@@ -22,13 +24,10 @@ interface DropboxFile {
 	document_id?: number;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{ name: string; args: Record<string, unknown> }>;
-	review_configs: Array<{ action_name: string; allowed_decisions: Array<"approve" | "reject"> }>;
-	context?: { account?: DropboxAccount; file?: DropboxFile; error?: string };
+interface DropboxTrashFileContext {
+	account?: DropboxAccount;
+	file?: DropboxFile;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -52,20 +51,12 @@ interface AuthErrorResult {
 }
 
 type DeleteDropboxFileResult =
-	| InterruptResult
+	| InterruptResult<DropboxTrashFileContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -95,12 +86,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DropboxTrashFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -308,16 +295,13 @@ export const DeleteDropboxFileToolUI = ({
 	{ file_name: string; delete_from_kb?: boolean },
 	DeleteDropboxFileResult
 >) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<DropboxTrashFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/google-drive/create-file.tsx b/surfsense_web/components/tool-ui/google-drive/create-file.tsx
index af263032d..2b77d5028 100644
--- a/surfsense_web/components/tool-ui/google-drive/create-file.tsx
+++ b/surfsense_web/components/tool-ui/google-drive/create-file.tsx
@@ -16,6 +16,8 @@ import {
 	SelectValue,
 } from "@/components/ui/select";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface GoogleDriveAccount {
 	id: number;
@@ -23,24 +25,11 @@ interface GoogleDriveAccount {
 	auth_expired?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: GoogleDriveAccount[];
-		supported_types?: string[];
-		parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
-		error?: string;
-	};
+interface DriveCreateFileContext {
+	accounts?: GoogleDriveAccount[];
+	supported_types?: string[];
+	parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -69,21 +58,12 @@ interface AuthErrorResult {
 }
 
 type CreateGoogleDriveFileResult =
-	| InterruptResult
+	| InterruptResult<DriveCreateFileContext>
 	| SuccessResult
 	| ErrorResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -122,12 +102,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { name: string; file_type: string; content?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DriveCreateFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -499,18 +475,15 @@ export const CreateGoogleDriveFileToolUI = ({
 	{ name: string; file_type: string; content?: string },
 	CreateGoogleDriveFileResult
 >) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<DriveCreateFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/google-drive/trash-file.tsx b/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
index f5ac11a3c..fa0bfc3bd 100644
--- a/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
@@ -7,6 +7,8 @@ import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface GoogleDriveAccount {
 	id: number;
@@ -21,23 +23,10 @@ interface GoogleDriveFile {
 	web_view_link: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	context?: {
-		account?: GoogleDriveAccount;
-		file?: GoogleDriveFile;
-		error?: string;
-	};
+interface DriveTrashFileContext {
+	account?: GoogleDriveAccount;
+	file?: GoogleDriveFile;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -77,7 +66,7 @@ interface AuthErrorResult {
 }
 
 type DeleteGoogleDriveFileResult =
-	| InterruptResult
+	| InterruptResult<DriveTrashFileContext>
 	| SuccessResult
 	| WarningResult
 	| ErrorResult
@@ -85,15 +74,6 @@ type DeleteGoogleDriveFileResult =
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -151,12 +131,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<DriveTrashFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -416,18 +392,14 @@ export const DeleteGoogleDriveFileToolUI = ({
 	{ file_name: string; delete_from_kb?: boolean },
 	DeleteGoogleDriveFileResult
 >) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<DriveTrashFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}

From 1c9c496e01b74b3f02cee6db3f71fc20cec66d51 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:21:46 +0530
Subject: [PATCH 12/28] feat: implement MCP Tool Trust methods for managing
 trusted tools

Added methods to trust and untrust tools in the MCP connector's "Always Allow" list, allowing for streamlined tool usage without HITL approval. This enhancement supports better management of trusted tools within the application.
---
 .../lib/apis/connectors-api.service.ts        | 39 ++++++++++++++++
 surfsense_web/lib/chat/streaming-state.ts     | 19 ++++++--
 surfsense_web/lib/hitl/index.ts               |  8 ++++
 surfsense_web/lib/hitl/types.ts               | 45 +++++++++++++++++++
 surfsense_web/lib/hitl/use-hitl-decision.ts   | 19 ++++++++
 5 files changed, 126 insertions(+), 4 deletions(-)
 create mode 100644 surfsense_web/lib/hitl/index.ts
 create mode 100644 surfsense_web/lib/hitl/types.ts
 create mode 100644 surfsense_web/lib/hitl/use-hitl-decision.ts

diff --git a/surfsense_web/lib/apis/connectors-api.service.ts b/surfsense_web/lib/apis/connectors-api.service.ts
index abd16c7a7..3eaa767c5 100644
--- a/surfsense_web/lib/apis/connectors-api.service.ts
+++ b/surfsense_web/lib/apis/connectors-api.service.ts
@@ -404,6 +404,45 @@ class ConnectorsApiService {
 			listDiscordChannelsResponse
 		);
 	};
+
+	// =============================================================================
+	// MCP Tool Trust (Allow-List) Methods
+	// =============================================================================
+
+	/**
+	 * Add a tool to the MCP connector's "Always Allow" list.
+	 * Subsequent calls to this tool will skip HITL approval.
+	 */
+	trustMCPTool = async (connectorId: number, toolName: string): Promise<void> => {
+		const backendUrl = process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL || "http://localhost:8000";
+		const token =
+			typeof window !== "undefined" ? document.cookie.match(/fapiToken=([^;]+)/)?.[1] : undefined;
+		await fetch(`${backendUrl}/api/v1/connectors/mcp/${connectorId}/trust-tool`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...(token ? { Authorization: `Bearer ${token}` } : {}),
+			},
+			body: JSON.stringify({ tool_name: toolName }),
+		});
+	};
+
+	/**
+	 * Remove a tool from the MCP connector's "Always Allow" list.
+	 */
+	untrustMCPTool = async (connectorId: number, toolName: string): Promise<void> => {
+		const backendUrl = process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL || "http://localhost:8000";
+		const token =
+			typeof window !== "undefined" ? document.cookie.match(/fapiToken=([^;]+)/)?.[1] : undefined;
+		await fetch(`${backendUrl}/api/v1/connectors/mcp/${connectorId}/untrust-tool`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...(token ? { Authorization: `Bearer ${token}` } : {}),
+			},
+			body: JSON.stringify({ tool_name: toolName }),
+		});
+	};
 }
 
 export type { SlackChannel, DiscordChannel };
diff --git a/surfsense_web/lib/chat/streaming-state.ts b/surfsense_web/lib/chat/streaming-state.ts
index 2f612a552..d54650d40 100644
--- a/surfsense_web/lib/chat/streaming-state.ts
+++ b/surfsense_web/lib/chat/streaming-state.ts
@@ -148,9 +148,10 @@ export function addToolCall(
 	toolsWithUI: Set<string>,
 	toolCallId: string,
 	toolName: string,
-	args: Record<string, unknown>
+	args: Record<string, unknown>,
+	force = false,
 ): void {
-	if (toolsWithUI.has(toolName)) {
+	if (force || toolsWithUI.has(toolName)) {
 		state.contentParts.push({
 			type: "tool-call",
 			toolCallId,
@@ -175,13 +176,20 @@ export function updateToolCall(
 	}
 }
 
+function _hasInterruptResult(part: ContentPart): boolean {
+	if (part.type !== "tool-call") return false;
+	const r = (part as { result?: unknown }).result;
+	return typeof r === "object" && r !== null && "__interrupt__" in r;
+}
+
 export function buildContentForUI(
 	state: ContentPartsState,
 	toolsWithUI: Set<string>
 ): ThreadMessageLike["content"] {
 	const filtered = state.contentParts.filter((part) => {
 		if (part.type === "text") return part.text.length > 0;
-		if (part.type === "tool-call") return toolsWithUI.has(part.toolName);
+		if (part.type === "tool-call")
+			return toolsWithUI.has(part.toolName) || _hasInterruptResult(part);
 		if (part.type === "data-thinking-steps") return true;
 		return false;
 	});
@@ -199,7 +207,10 @@ export function buildContentForPersistence(
 	for (const part of state.contentParts) {
 		if (part.type === "text" && part.text.length > 0) {
 			parts.push(part);
-		} else if (part.type === "tool-call" && toolsWithUI.has(part.toolName)) {
+		} else if (
+			part.type === "tool-call" &&
+			(toolsWithUI.has(part.toolName) || _hasInterruptResult(part))
+		) {
 			parts.push(part);
 		} else if (part.type === "data-thinking-steps") {
 			parts.push(part);
diff --git a/surfsense_web/lib/hitl/index.ts b/surfsense_web/lib/hitl/index.ts
new file mode 100644
index 000000000..14c791d02
--- /dev/null
+++ b/surfsense_web/lib/hitl/index.ts
@@ -0,0 +1,8 @@
+export { isInterruptResult } from "./types";
+export type {
+	HitlDecision,
+	InterruptActionRequest,
+	InterruptResult,
+	InterruptReviewConfig,
+} from "./types";
+export { useHitlDecision } from "./use-hitl-decision";
diff --git a/surfsense_web/lib/hitl/types.ts b/surfsense_web/lib/hitl/types.ts
new file mode 100644
index 000000000..53df61145
--- /dev/null
+++ b/surfsense_web/lib/hitl/types.ts
@@ -0,0 +1,45 @@
+/**
+ * Shared types for Human-in-the-Loop (HITL) approval across all tools.
+ *
+ * Every tool-ui component that handles interrupts should import from here
+ * instead of defining its own `InterruptResult` / `isInterruptResult`.
+ */
+
+export interface InterruptActionRequest {
+	name: string;
+	args: Record<string, unknown>;
+}
+
+export interface InterruptReviewConfig {
+	action_name: string;
+	allowed_decisions: Array<"approve" | "edit" | "reject">;
+}
+
+export interface InterruptResult<C extends Record<string, unknown> = Record<string, unknown>> {
+	__interrupt__: true;
+	__decided__?: "approve" | "reject" | "edit";
+	__completed__?: boolean;
+	action_requests: InterruptActionRequest[];
+	review_configs: InterruptReviewConfig[];
+	interrupt_type?: string;
+	context?: C;
+	message?: string;
+}
+
+export function isInterruptResult(result: unknown): result is InterruptResult {
+	return (
+		typeof result === "object" &&
+		result !== null &&
+		"__interrupt__" in result &&
+		(result as InterruptResult).__interrupt__ === true
+	);
+}
+
+export interface HitlDecision {
+	type: "approve" | "reject" | "edit";
+	message?: string;
+	edited_action?: {
+		name: string;
+		args: Record<string, unknown>;
+	};
+}
diff --git a/surfsense_web/lib/hitl/use-hitl-decision.ts b/surfsense_web/lib/hitl/use-hitl-decision.ts
new file mode 100644
index 000000000..f7f85ab88
--- /dev/null
+++ b/surfsense_web/lib/hitl/use-hitl-decision.ts
@@ -0,0 +1,19 @@
+/**
+ * Shared hook for dispatching HITL decisions.
+ *
+ * All tool-ui components that handle approve/reject/edit should use this
+ * instead of manually constructing `CustomEvent("hitl-decision", ...)`.
+ */
+
+import { useCallback } from "react";
+import type { HitlDecision } from "./types";
+
+export function useHitlDecision() {
+	const dispatch = useCallback((decisions: HitlDecision[]) => {
+		window.dispatchEvent(
+			new CustomEvent("hitl-decision", { detail: { decisions } }),
+		);
+	}, []);
+
+	return { dispatch };
+}

From e6065b67932286695a0fe20badd7be93f98c27c0 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:22:26 +0530
Subject: [PATCH 13/28] refactor: unify interrupt handling in Gmail and Google
 Calendar tools

Refactored the create, send, update, and delete functionalities in Gmail and Google Calendar tools to utilize a consistent InterruptResult interface with specific context types. This change enhances code clarity and maintains uniformity in handling user approvals by integrating the useHitlDecision hook for decision dispatching.
---
 .../components/tool-ui/gmail/create-draft.tsx | 50 ++++------------
 .../components/tool-ui/gmail/send-email.tsx   | 50 ++++------------
 .../components/tool-ui/gmail/trash-email.tsx  | 53 +++++------------
 .../components/tool-ui/gmail/update-draft.tsx | 58 +++++--------------
 .../tool-ui/google-calendar/create-event.tsx  | 54 +++++------------
 .../tool-ui/google-calendar/delete-event.tsx  | 53 +++++------------
 .../tool-ui/google-calendar/update-event.tsx  | 52 +++++------------
 7 files changed, 92 insertions(+), 278 deletions(-)

diff --git a/surfsense_web/components/tool-ui/gmail/create-draft.tsx b/surfsense_web/components/tool-ui/gmail/create-draft.tsx
index 97e93fecb..73e5bcd61 100644
--- a/surfsense_web/components/tool-ui/gmail/create-draft.tsx
+++ b/surfsense_web/components/tool-ui/gmail/create-draft.tsx
@@ -16,6 +16,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GmailAccount {
@@ -25,22 +27,9 @@ interface GmailAccount {
 	auth_expired?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: GmailAccount[];
-		error?: string;
-	};
+interface GmailCreateDraftContext {
+	accounts?: GmailAccount[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -68,21 +57,12 @@ interface InsufficientPermissionsResult {
 }
 
 type CreateGmailDraftResult =
-	| InterruptResult
+	| InterruptResult<GmailCreateDraftContext>
 	| SuccessResult
 	| ErrorResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -116,12 +96,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { to: string; subject: string; body: string; cc?: string; bcc?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<GmailCreateDraftContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -473,18 +449,16 @@ export const CreateGmailDraftToolUI = ({
 	{ to: string; subject: string; body: string; cc?: string; bcc?: string },
 	CreateGmailDraftResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<GmailCreateDraftContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/gmail/send-email.tsx b/surfsense_web/components/tool-ui/gmail/send-email.tsx
index e0e1ffa6c..c95e67d6e 100644
--- a/surfsense_web/components/tool-ui/gmail/send-email.tsx
+++ b/surfsense_web/components/tool-ui/gmail/send-email.tsx
@@ -16,6 +16,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GmailAccount {
@@ -25,22 +27,9 @@ interface GmailAccount {
 	auth_expired?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: GmailAccount[];
-		error?: string;
-	};
+interface GmailSendEmailContext {
+	accounts?: GmailAccount[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -67,21 +56,12 @@ interface InsufficientPermissionsResult {
 }
 
 type SendGmailEmailResult =
-	| InterruptResult
+	| InterruptResult<GmailSendEmailContext>
 	| SuccessResult
 	| ErrorResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -115,12 +95,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { to: string; subject: string; body: string; cc?: string; bcc?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<GmailSendEmailContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -471,18 +447,16 @@ export const SendGmailEmailToolUI = ({
 	{ to: string; subject: string; body: string; cc?: string; bcc?: string },
 	SendGmailEmailResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<GmailSendEmailContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/gmail/trash-email.tsx b/surfsense_web/components/tool-ui/gmail/trash-email.tsx
index f1640f3fc..b3090a364 100644
--- a/surfsense_web/components/tool-ui/gmail/trash-email.tsx
+++ b/surfsense_web/components/tool-ui/gmail/trash-email.tsx
@@ -6,6 +6,8 @@ import { useCallback, useEffect, useState } from "react";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GmailAccount {
@@ -25,23 +27,10 @@ interface GmailMessage {
 	document_id: number;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	context?: {
-		account?: GmailAccount;
-		email?: GmailMessage;
-		error?: string;
-	};
+interface GmailTrashEmailContext {
+	account?: GmailAccount;
+	email?: GmailMessage;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -74,22 +63,13 @@ interface InsufficientPermissionsResult {
 }
 
 type TrashGmailEmailResult =
-	| InterruptResult
+	| InterruptResult<GmailTrashEmailContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -134,12 +114,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<GmailTrashEmailContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -385,18 +361,15 @@ export const TrashGmailEmailToolUI = ({
 	{ email_subject_or_id: string; delete_from_kb?: boolean },
 	TrashGmailEmailResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<GmailTrashEmailContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/gmail/update-draft.tsx b/surfsense_web/components/tool-ui/gmail/update-draft.tsx
index b3b0d2d21..431744463 100644
--- a/surfsense_web/components/tool-ui/gmail/update-draft.tsx
+++ b/surfsense_web/components/tool-ui/gmail/update-draft.tsx
@@ -9,6 +9,8 @@ import { openHitlEditPanelAtom } from "@/atoms/chat/hitl-edit-panel.atom";
 import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GmailAccount {
@@ -28,25 +30,12 @@ interface GmailMessage {
 	document_id: number;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		account?: GmailAccount;
-		email?: GmailMessage;
-		draft_id?: string;
-		existing_body?: string;
-		error?: string;
-	};
+interface GmailUpdateDraftContext {
+	account?: GmailAccount;
+	email?: GmailMessage;
+	draft_id?: string;
+	existing_body?: string;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -78,22 +67,13 @@ interface InsufficientPermissionsResult {
 }
 
 type UpdateGmailDraftResult =
-	| InterruptResult
+	| InterruptResult<GmailUpdateDraftContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -143,12 +123,8 @@ function ApprovalCard({
 		cc?: string;
 		bcc?: string;
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<GmailUpdateDraftContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -522,20 +498,16 @@ export const UpdateGmailDraftToolUI = ({
 	},
 	UpdateGmailDraftResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", {
-							detail: { decisions: [decision] },
-						})
-					);
-				}}
+				interruptData={result as InterruptResult<GmailUpdateDraftContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/google-calendar/create-event.tsx b/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
index 37e5028e7..e45c51775 100644
--- a/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
@@ -16,6 +16,8 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@/components/ui/select";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GoogleCalendarAccount {
@@ -30,24 +32,11 @@ interface CalendarEntry {
 	primary?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: GoogleCalendarAccount[];
-		calendars?: CalendarEntry[];
-		timezone?: string;
-		error?: string;
-	};
+interface CalendarCreateEventContext {
+	accounts?: GoogleCalendarAccount[];
+	calendars?: CalendarEntry[];
+	timezone?: string;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -75,21 +64,12 @@ interface InsufficientPermissionsResult {
 }
 
 type CreateCalendarEventResult =
-	| InterruptResult
+	| InterruptResult<CalendarCreateEventContext>
 	| SuccessResult
 	| ErrorResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -141,12 +121,8 @@ function ApprovalCard({
 		location?: string;
 		attendees?: string[];
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<CalendarCreateEventContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -620,18 +596,16 @@ export const CreateCalendarEventToolUI = ({
 	},
 	CreateCalendarEventResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<CalendarCreateEventContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx b/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
index 039c0e3b0..16e0a4112 100644
--- a/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
@@ -6,6 +6,8 @@ import { useCallback, useEffect, useState } from "react";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GoogleCalendarAccount {
@@ -27,23 +29,10 @@ interface CalendarEvent {
 	indexed_at?: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	context?: {
-		account?: GoogleCalendarAccount;
-		event?: CalendarEvent;
-		error?: string;
-	};
+interface CalendarDeleteEventContext {
+	account?: GoogleCalendarAccount;
+	event?: CalendarEvent;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -83,7 +72,7 @@ interface InsufficientPermissionsResult {
 }
 
 type DeleteCalendarEventResult =
-	| InterruptResult
+	| InterruptResult<CalendarDeleteEventContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
@@ -91,15 +80,6 @@ type DeleteCalendarEventResult =
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -162,12 +142,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<CalendarDeleteEventContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -437,18 +413,15 @@ export const DeleteCalendarEventToolUI = ({
 	{ event_title_or_id: string; delete_from_kb?: boolean },
 	DeleteCalendarEventResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<CalendarDeleteEventContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/google-calendar/update-event.tsx b/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
index a2304b179..541c59378 100644
--- a/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
@@ -16,6 +16,8 @@ import { openHitlEditPanelAtom } from "@/atoms/chat/hitl-edit-panel.atom";
 import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { HitlDecision, InterruptResult } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
 interface GoogleCalendarAccount {
@@ -37,23 +39,10 @@ interface CalendarEvent {
 	indexed_at?: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		account?: GoogleCalendarAccount;
-		event?: CalendarEvent;
-		error?: string;
-	};
+interface CalendarUpdateEventContext {
+	account?: GoogleCalendarAccount;
+	event?: CalendarEvent;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -86,22 +75,13 @@ interface InsufficientPermissionsResult {
 }
 
 type UpdateCalendarEventResult =
-	| InterruptResult
+	| InterruptResult<CalendarUpdateEventContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| InsufficientPermissionsResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -163,12 +143,8 @@ function ApprovalCard({
 		new_location?: string;
 		new_attendees?: string[];
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<CalendarUpdateEventContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const actionArgs = interruptData.action_requests[0]?.args ?? {};
@@ -686,18 +662,16 @@ export const UpdateCalendarEventToolUI = ({
 	},
 	UpdateCalendarEventResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<CalendarUpdateEventContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}

From 5169d3d56c61434edc6541c666cbf61540cc563f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:22:47 +0530
Subject: [PATCH 14/28] refactor: unify interrupt handling in Linear and Notion
 tools

Refactored the create, update, and delete functionalities in Linear and Notion tools to utilize a consistent InterruptResult interface with specific context types. This change enhances code clarity and maintains uniformity in handling user approvals by integrating the useHitlDecision hook for decision dispatching.
---
 .../tool-ui/linear/create-linear-issue.tsx    | 51 +++-------
 .../tool-ui/linear/delete-linear-issue.tsx    | 66 ++++---------
 .../tool-ui/linear/update-linear-issue.tsx    | 93 +++++++------------
 .../tool-ui/notion/create-notion-page.tsx     | 80 +++++-----------
 .../tool-ui/notion/delete-notion-page.tsx     | 70 ++++----------
 .../tool-ui/notion/update-notion-page.tsx     | 70 ++++----------
 6 files changed, 129 insertions(+), 301 deletions(-)

diff --git a/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
index 1dec11c60..156cdb5ca 100644
--- a/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
@@ -18,6 +18,8 @@ import {
 } from "@/components/ui/select";
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface LinearLabel {
 	id: string;
@@ -64,23 +66,9 @@ interface LinearWorkspace {
 	auth_expired?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		workspaces?: LinearWorkspace[];
-		error?: string;
-	};
+interface LinearCreateIssueContext {
+	workspaces?: LinearWorkspace[];
+	error?: string;
 }
 
 interface SuccessResult {
@@ -103,16 +91,7 @@ interface AuthErrorResult {
 	connector_type: string;
 }
 
-type CreateLinearIssueResult = InterruptResult | SuccessResult | ErrorResult | AuthErrorResult;
-
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
+type CreateLinearIssueResult = InterruptResult<LinearCreateIssueContext> | SuccessResult | ErrorResult | AuthErrorResult;
 
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
@@ -138,12 +117,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { title: string; description?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<LinearCreateIssueContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -609,18 +584,16 @@ export const CreateLinearIssueToolUI = ({
 	args,
 	result,
 }: ToolCallMessagePartProps<{ title: string; description?: string }, CreateLinearIssueResult>) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<LinearCreateIssueContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
index 18790f560..f033240de 100644
--- a/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
@@ -7,32 +7,20 @@ import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		workspace?: { id: number; organization_name: string };
-		issue?: {
-			id: string;
-			identifier: string;
-			title: string;
-			state?: string;
-			document_id?: number;
-			indexed_at?: string;
-		};
-		error?: string;
+interface LinearDeleteIssueContext {
+	workspace?: { id: number; organization_name: string };
+	issue?: {
+		id: string;
+		identifier: string;
+		title: string;
+		state?: string;
+		document_id?: number;
+		indexed_at?: string;
 	};
+	error?: string;
 }
 
 interface SuccessResult {
@@ -65,22 +53,13 @@ interface AuthErrorResult {
 }
 
 type DeleteLinearIssueResult =
-	| InterruptResult
+	| InterruptResult<LinearDeleteIssueContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| WarningResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -123,12 +102,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<LinearDeleteIssueContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -366,18 +341,15 @@ export const DeleteLinearIssueToolUI = ({
 	{ issue_ref: string; delete_from_kb?: boolean },
 	DeleteLinearIssueResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<LinearDeleteIssueContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
index f15f04224..4ff5b6e75 100644
--- a/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
@@ -18,6 +18,8 @@ import {
 } from "@/components/ui/select";
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface LinearLabel {
 	id: string;
@@ -45,45 +47,31 @@ interface LinearPriority {
 	label: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
-		name: string;
-		args: Record<string, unknown>;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	context?: {
-		workspace?: { id: number; organization_name: string };
-		priorities?: LinearPriority[];
-		issue?: {
-			id: string;
-			identifier: string;
-			title: string;
-			description?: string;
-			priority: number;
-			url: string;
-			current_state?: LinearState;
-			current_assignee?: { id: string; name: string; email: string } | null;
-			current_labels?: LinearLabel[];
-			team_id: string;
-			document_id: number;
-		};
-		team?: {
-			id: string;
-			name: string;
-			key: string;
-			states: LinearState[];
-			members: LinearMember[];
-			labels: LinearLabel[];
-		};
-		error?: string;
+interface LinearUpdateIssueContext {
+	workspace?: { id: number; organization_name: string };
+	priorities?: LinearPriority[];
+	issue?: {
+		id: string;
+		identifier: string;
+		title: string;
+		description?: string;
+		priority: number;
+		url: string;
+		current_state?: LinearState;
+		current_assignee?: { id: string; name: string; email: string } | null;
+		current_labels?: LinearLabel[];
+		team_id: string;
+		document_id: number;
 	};
+	team?: {
+		id: string;
+		name: string;
+		key: string;
+		states: LinearState[];
+		members: LinearMember[];
+		labels: LinearLabel[];
+	};
+	error?: string;
 }
 
 interface SuccessResult {
@@ -111,21 +99,12 @@ interface AuthErrorResult {
 }
 
 type UpdateLinearIssueResult =
-	| InterruptResult
+	| InterruptResult<LinearUpdateIssueContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -167,12 +146,8 @@ function ApprovalCard({
 		new_priority?: number;
 		new_label_names?: string[];
 	};
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<LinearUpdateIssueContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 
@@ -752,18 +727,16 @@ export const UpdateLinearIssueToolUI = ({
 	},
 	UpdateLinearIssueResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<LinearUpdateIssueContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/notion/create-notion-page.tsx b/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
index 52ac363ee..9a05dbc94 100644
--- a/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
@@ -16,41 +16,27 @@ import {
 	SelectValue,
 } from "@/components/ui/select";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
+interface NotionCreatePageContext {
+	accounts?: Array<{
+		id: number;
 		name: string;
-		args: Record<string, unknown>;
-		description?: string;
+		workspace_id: string | null;
+		workspace_name: string;
+		workspace_icon: string;
+		auth_expired?: boolean;
 	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	message?: string;
-	context?: {
-		accounts?: Array<{
-			id: number;
-			name: string;
-			workspace_id: string | null;
-			workspace_name: string;
-			workspace_icon: string;
-			auth_expired?: boolean;
-		}>;
-		parent_pages?: Record<
-			number,
-			Array<{
-				page_id: string;
-				title: string;
-				document_id: number;
-			}>
-		>;
-		error?: string;
-	};
+	parent_pages?: Record<
+		number,
+		Array<{
+			page_id: string;
+			title: string;
+			document_id: number;
+		}>
+	>;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -75,16 +61,7 @@ interface AuthErrorResult {
 	connector_type: string;
 }
 
-type CreateNotionPageResult = InterruptResult | SuccessResult | ErrorResult | AuthErrorResult;
-
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
+type CreateNotionPageResult = InterruptResult<NotionCreatePageContext> | SuccessResult | ErrorResult | AuthErrorResult;
 
 function isAuthErrorResult(result: unknown): result is AuthErrorResult {
 	return (
@@ -110,12 +87,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: Record<string, unknown>;
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<NotionCreatePageContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -449,19 +422,16 @@ export const CreateNotionPageToolUI = ({
 	args,
 	result,
 }: ToolCallMessagePartProps<{ title: string; content: string }, CreateNotionPageResult>) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<NotionCreatePageContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx b/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
index 792a3e8c4..5f30c7efd 100644
--- a/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
@@ -7,36 +7,22 @@ import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{
+interface NotionDeletePageContext {
+	account?: {
+		id: number;
 		name: string;
-		args: Record<string, unknown>;
-		description?: string;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "reject">;
-	}>;
-	interrupt_type?: string;
-	message?: string;
-	context?: {
-		account?: {
-			id: number;
-			name: string;
-			workspace_id: string | null;
-			workspace_name: string;
-			workspace_icon: string;
-		};
-		page_id?: string;
-		current_title?: string;
-		document_id?: number;
-		indexed_at?: string;
-		error?: string;
+		workspace_id: string | null;
+		workspace_name: string;
+		workspace_icon: string;
 	};
+	page_id?: string;
+	current_title?: string;
+	document_id?: number;
+	indexed_at?: string;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -73,22 +59,13 @@ interface AuthErrorResult {
 }
 
 type DeleteNotionPageResult =
-	| InterruptResult
+	| InterruptResult<NotionDeletePageContext>
 	| SuccessResult
 	| ErrorResult
 	| InfoResult
 	| WarningResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -131,12 +108,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<NotionDeletePageContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -378,18 +351,15 @@ export const DeleteNotionPageToolUI = ({
 	{ page_title: string; delete_from_kb?: boolean },
 	DeleteNotionPageResult
 >) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<NotionDeletePageContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/notion/update-notion-page.tsx b/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
index 5b7ce7daa..d07c6592b 100644
--- a/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
@@ -9,36 +9,22 @@ import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{
+interface NotionUpdatePageContext {
+	account?: {
+		id: number;
 		name: string;
-		args: Record<string, unknown>;
-		description?: string;
-	}>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	interrupt_type?: string;
-	message?: string;
-	context?: {
-		account?: {
-			id: number;
-			name: string;
-			workspace_id: string | null;
-			workspace_name: string;
-			workspace_icon: string;
-		};
-		page_id?: string;
-		current_title?: string;
-		document_id?: number;
-		indexed_at?: string;
-		error?: string;
+		workspace_id: string | null;
+		workspace_name: string;
+		workspace_icon: string;
 	};
+	page_id?: string;
+	current_title?: string;
+	document_id?: number;
+	indexed_at?: string;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -69,21 +55,12 @@ interface AuthErrorResult {
 }
 
 type UpdateNotionPageResult =
-	| InterruptResult
+	| InterruptResult<NotionUpdatePageContext>
 	| SuccessResult
 	| ErrorResult
 	| InfoResult
 	| AuthErrorResult;
 
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
-
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -117,12 +94,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: Record<string, unknown>;
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<NotionUpdatePageContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -399,19 +372,16 @@ export const UpdateNotionPageToolUI = ({
 	args,
 	result,
 }: ToolCallMessagePartProps<{ page_title: string; content: string }, UpdateNotionPageResult>) => {
+	const { dispatch } = useHitlDecision();
+
 	if (!result) return null;
 
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					const event = new CustomEvent("hitl-decision", {
-						detail: { decisions: [decision] },
-					});
-					window.dispatchEvent(event);
-				}}
+				interruptData={result as InterruptResult<NotionUpdatePageContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}

From 041af348201ff12d400892f91b32d143b0e209de Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:23:03 +0530
Subject: [PATCH 15/28] refactor: unify interrupt handling in OneDrive tools

Refactored the create and delete file functionalities in OneDrive tools to utilize a consistent InterruptResult interface with specific context types. This change enhances code clarity and maintains uniformity in handling user approvals by integrating the useHitlDecision hook for decision dispatching.
---
 .../tool-ui/onedrive/create-file.tsx          | 48 +++++--------------
 .../tool-ui/onedrive/trash-file.tsx           | 41 +++++-----------
 2 files changed, 24 insertions(+), 65 deletions(-)

diff --git a/surfsense_web/components/tool-ui/onedrive/create-file.tsx b/surfsense_web/components/tool-ui/onedrive/create-file.tsx
index 244b894dc..502394986 100644
--- a/surfsense_web/components/tool-ui/onedrive/create-file.tsx
+++ b/surfsense_web/components/tool-ui/onedrive/create-file.tsx
@@ -16,6 +16,8 @@ import {
 	SelectValue,
 } from "@/components/ui/select";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface OneDriveAccount {
 	id: number;
@@ -24,20 +26,10 @@ interface OneDriveAccount {
 	auth_expired?: boolean;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject" | "edit";
-	__completed__?: boolean;
-	action_requests: Array<{ name: string; args: Record<string, unknown> }>;
-	review_configs: Array<{
-		action_name: string;
-		allowed_decisions: Array<"approve" | "edit" | "reject">;
-	}>;
-	context?: {
-		accounts?: OneDriveAccount[];
-		parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
-		error?: string;
-	};
+interface OneDriveCreateFileContext {
+	accounts?: OneDriveAccount[];
+	parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -59,16 +51,7 @@ interface AuthErrorResult {
 	connector_type?: string;
 }
 
-type CreateOneDriveFileResult = InterruptResult | SuccessResult | ErrorResult | AuthErrorResult;
-
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
+type CreateOneDriveFileResult = InterruptResult<OneDriveCreateFileContext> | SuccessResult | ErrorResult | AuthErrorResult;
 
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
@@ -94,12 +77,8 @@ function ApprovalCard({
 	onDecision,
 }: {
 	args: { name: string; content?: string };
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject" | "edit";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<OneDriveCreateFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
@@ -434,17 +413,14 @@ export const CreateOneDriveFileToolUI = ({
 	args,
 	result,
 }: ToolCallMessagePartProps<{ name: string; content?: string }, CreateOneDriveFileResult>) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
 				args={args}
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<OneDriveCreateFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}
diff --git a/surfsense_web/components/tool-ui/onedrive/trash-file.tsx b/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
index b5d2e3d67..5735363c0 100644
--- a/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
@@ -7,6 +7,8 @@ import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
+import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
+import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
 interface OneDriveAccount {
 	id: number;
@@ -22,13 +24,10 @@ interface OneDriveFile {
 	web_url?: string;
 }
 
-interface InterruptResult {
-	__interrupt__: true;
-	__decided__?: "approve" | "reject";
-	__completed__?: boolean;
-	action_requests: Array<{ name: string; args: Record<string, unknown> }>;
-	review_configs: Array<{ action_name: string; allowed_decisions: Array<"approve" | "reject"> }>;
-	context?: { account?: OneDriveAccount; file?: OneDriveFile; error?: string };
+interface OneDriveTrashFileContext {
+	account?: OneDriveAccount;
+	file?: OneDriveFile;
+	error?: string;
 }
 
 interface SuccessResult {
@@ -52,20 +51,11 @@ interface AuthErrorResult {
 }
 
 type DeleteOneDriveFileResult =
-	| InterruptResult
+	| InterruptResult<OneDriveTrashFileContext>
 	| SuccessResult
 	| ErrorResult
 	| NotFoundResult
 	| AuthErrorResult;
-
-function isInterruptResult(result: unknown): result is InterruptResult {
-	return (
-		typeof result === "object" &&
-		result !== null &&
-		"__interrupt__" in result &&
-		(result as InterruptResult).__interrupt__ === true
-	);
-}
 function isErrorResult(result: unknown): result is ErrorResult {
 	return (
 		typeof result === "object" &&
@@ -95,12 +85,8 @@ function ApprovalCard({
 	interruptData,
 	onDecision,
 }: {
-	interruptData: InterruptResult;
-	onDecision: (decision: {
-		type: "approve" | "reject";
-		message?: string;
-		edited_action?: { name: string; args: Record<string, unknown> };
-	}) => void;
+	interruptData: InterruptResult<OneDriveTrashFileContext>;
+	onDecision: (decision: HitlDecision) => void;
 }) {
 	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [deleteFromKb, setDeleteFromKb] = useState(false);
@@ -311,16 +297,13 @@ export const DeleteOneDriveFileToolUI = ({
 	{ file_name: string; delete_from_kb?: boolean },
 	DeleteOneDriveFileResult
 >) => {
+	const { dispatch } = useHitlDecision();
 	if (!result) return null;
 	if (isInterruptResult(result)) {
 		return (
 			<ApprovalCard
-				interruptData={result}
-				onDecision={(decision) => {
-					window.dispatchEvent(
-						new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-					);
-				}}
+				interruptData={result as InterruptResult<OneDriveTrashFileContext>}
+				onDecision={(decision) => dispatch([decision])}
 			/>
 		);
 	}

From 71f4f77f26671f752706c66965e36f99629e52f2 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 20:25:49 +0530
Subject: [PATCH 16/28] refactor: unify interrupt handling in various tools

Refactored the context types for create, delete, and update functionalities across multiple tools including Confluence, Dropbox, Gmail, Google Calendar, Jira, Linear, Notion, and OneDrive to utilize a consistent type definition. This change enhances code clarity and maintains uniformity in handling user approvals by integrating the useHitlDecision hook for decision dispatching.
---
 .../components/tool-ui/confluence/create-confluence-page.tsx    | 2 +-
 .../components/tool-ui/confluence/delete-confluence-page.tsx    | 2 +-
 .../components/tool-ui/confluence/update-confluence-page.tsx    | 2 +-
 surfsense_web/components/tool-ui/dropbox/create-file.tsx        | 2 +-
 surfsense_web/components/tool-ui/dropbox/trash-file.tsx         | 2 +-
 surfsense_web/components/tool-ui/gmail/create-draft.tsx         | 2 +-
 surfsense_web/components/tool-ui/gmail/send-email.tsx           | 2 +-
 surfsense_web/components/tool-ui/gmail/trash-email.tsx          | 2 +-
 surfsense_web/components/tool-ui/gmail/update-draft.tsx         | 2 +-
 .../components/tool-ui/google-calendar/create-event.tsx         | 2 +-
 .../components/tool-ui/google-calendar/delete-event.tsx         | 2 +-
 .../components/tool-ui/google-calendar/update-event.tsx         | 2 +-
 surfsense_web/components/tool-ui/google-drive/create-file.tsx   | 2 +-
 surfsense_web/components/tool-ui/google-drive/trash-file.tsx    | 2 +-
 surfsense_web/components/tool-ui/jira/create-jira-issue.tsx     | 2 +-
 surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx     | 2 +-
 surfsense_web/components/tool-ui/jira/update-jira-issue.tsx     | 2 +-
 surfsense_web/components/tool-ui/linear/create-linear-issue.tsx | 2 +-
 surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx | 2 +-
 surfsense_web/components/tool-ui/linear/update-linear-issue.tsx | 2 +-
 surfsense_web/components/tool-ui/notion/create-notion-page.tsx  | 2 +-
 surfsense_web/components/tool-ui/notion/delete-notion-page.tsx  | 2 +-
 surfsense_web/components/tool-ui/notion/update-notion-page.tsx  | 2 +-
 surfsense_web/components/tool-ui/onedrive/create-file.tsx       | 2 +-
 surfsense_web/components/tool-ui/onedrive/trash-file.tsx        | 2 +-
 25 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
index b60817536..f8cd6ee15 100644
--- a/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/create-confluence-page.tsx
@@ -32,7 +32,7 @@ interface ConfluenceSpace {
 	name: string;
 }
 
-interface CreateConfluencePageInterruptContext {
+type CreateConfluencePageInterruptContext = {
 	accounts?: ConfluenceAccount[];
 	spaces?: ConfluenceSpace[];
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
index ca45e26ee..37d73377e 100644
--- a/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/delete-confluence-page.tsx
@@ -10,7 +10,7 @@ import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
-interface DeleteConfluencePageInterruptContext {
+type DeleteConfluencePageInterruptContext = {
 	account?: {
 		id: number;
 		name: string;
diff --git a/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx b/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
index 7f75f9ac8..76df10e40 100644
--- a/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
+++ b/surfsense_web/components/tool-ui/confluence/update-confluence-page.tsx
@@ -12,7 +12,7 @@ import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 import { useHitlPhase } from "@/hooks/use-hitl-phase";
 
-interface UpdateConfluencePageInterruptContext {
+type UpdateConfluencePageInterruptContext = {
 	account?: {
 		id: number;
 		name: string;
diff --git a/surfsense_web/components/tool-ui/dropbox/create-file.tsx b/surfsense_web/components/tool-ui/dropbox/create-file.tsx
index 70daf491c..15d454c76 100644
--- a/surfsense_web/components/tool-ui/dropbox/create-file.tsx
+++ b/surfsense_web/components/tool-ui/dropbox/create-file.tsx
@@ -31,7 +31,7 @@ interface SupportedType {
 	label: string;
 }
 
-interface DropboxCreateFileContext {
+type DropboxCreateFileContext = {
 	accounts?: DropboxAccount[];
 	parent_folders?: Record<number, Array<{ folder_path: string; name: string }>>;
 	supported_types?: SupportedType[];
diff --git a/surfsense_web/components/tool-ui/dropbox/trash-file.tsx b/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
index 3d4ad8a94..a2fadd20f 100644
--- a/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/dropbox/trash-file.tsx
@@ -24,7 +24,7 @@ interface DropboxFile {
 	document_id?: number;
 }
 
-interface DropboxTrashFileContext {
+type DropboxTrashFileContext = {
 	account?: DropboxAccount;
 	file?: DropboxFile;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/gmail/create-draft.tsx b/surfsense_web/components/tool-ui/gmail/create-draft.tsx
index 73e5bcd61..d13ee2d94 100644
--- a/surfsense_web/components/tool-ui/gmail/create-draft.tsx
+++ b/surfsense_web/components/tool-ui/gmail/create-draft.tsx
@@ -27,7 +27,7 @@ interface GmailAccount {
 	auth_expired?: boolean;
 }
 
-interface GmailCreateDraftContext {
+type GmailCreateDraftContext = {
 	accounts?: GmailAccount[];
 	error?: string;
 }
diff --git a/surfsense_web/components/tool-ui/gmail/send-email.tsx b/surfsense_web/components/tool-ui/gmail/send-email.tsx
index c95e67d6e..8a632e582 100644
--- a/surfsense_web/components/tool-ui/gmail/send-email.tsx
+++ b/surfsense_web/components/tool-ui/gmail/send-email.tsx
@@ -27,7 +27,7 @@ interface GmailAccount {
 	auth_expired?: boolean;
 }
 
-interface GmailSendEmailContext {
+type GmailSendEmailContext = {
 	accounts?: GmailAccount[];
 	error?: string;
 }
diff --git a/surfsense_web/components/tool-ui/gmail/trash-email.tsx b/surfsense_web/components/tool-ui/gmail/trash-email.tsx
index b3090a364..ca2f8f074 100644
--- a/surfsense_web/components/tool-ui/gmail/trash-email.tsx
+++ b/surfsense_web/components/tool-ui/gmail/trash-email.tsx
@@ -27,7 +27,7 @@ interface GmailMessage {
 	document_id: number;
 }
 
-interface GmailTrashEmailContext {
+type GmailTrashEmailContext = {
 	account?: GmailAccount;
 	email?: GmailMessage;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/gmail/update-draft.tsx b/surfsense_web/components/tool-ui/gmail/update-draft.tsx
index 431744463..512808344 100644
--- a/surfsense_web/components/tool-ui/gmail/update-draft.tsx
+++ b/surfsense_web/components/tool-ui/gmail/update-draft.tsx
@@ -30,7 +30,7 @@ interface GmailMessage {
 	document_id: number;
 }
 
-interface GmailUpdateDraftContext {
+type GmailUpdateDraftContext = {
 	account?: GmailAccount;
 	email?: GmailMessage;
 	draft_id?: string;
diff --git a/surfsense_web/components/tool-ui/google-calendar/create-event.tsx b/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
index e45c51775..71a78d826 100644
--- a/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/create-event.tsx
@@ -32,7 +32,7 @@ interface CalendarEntry {
 	primary?: boolean;
 }
 
-interface CalendarCreateEventContext {
+type CalendarCreateEventContext = {
 	accounts?: GoogleCalendarAccount[];
 	calendars?: CalendarEntry[];
 	timezone?: string;
diff --git a/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx b/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
index 16e0a4112..1d3186a2f 100644
--- a/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/delete-event.tsx
@@ -29,7 +29,7 @@ interface CalendarEvent {
 	indexed_at?: string;
 }
 
-interface CalendarDeleteEventContext {
+type CalendarDeleteEventContext = {
 	account?: GoogleCalendarAccount;
 	event?: CalendarEvent;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/google-calendar/update-event.tsx b/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
index 541c59378..1489a7da0 100644
--- a/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
+++ b/surfsense_web/components/tool-ui/google-calendar/update-event.tsx
@@ -39,7 +39,7 @@ interface CalendarEvent {
 	indexed_at?: string;
 }
 
-interface CalendarUpdateEventContext {
+type CalendarUpdateEventContext = {
 	account?: GoogleCalendarAccount;
 	event?: CalendarEvent;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/google-drive/create-file.tsx b/surfsense_web/components/tool-ui/google-drive/create-file.tsx
index 2b77d5028..dba06c64d 100644
--- a/surfsense_web/components/tool-ui/google-drive/create-file.tsx
+++ b/surfsense_web/components/tool-ui/google-drive/create-file.tsx
@@ -25,7 +25,7 @@ interface GoogleDriveAccount {
 	auth_expired?: boolean;
 }
 
-interface DriveCreateFileContext {
+type DriveCreateFileContext = {
 	accounts?: GoogleDriveAccount[];
 	supported_types?: string[];
 	parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
diff --git a/surfsense_web/components/tool-ui/google-drive/trash-file.tsx b/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
index fa0bfc3bd..e28855570 100644
--- a/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/google-drive/trash-file.tsx
@@ -23,7 +23,7 @@ interface GoogleDriveFile {
 	web_view_link: string;
 }
 
-interface DriveTrashFileContext {
+type DriveTrashFileContext = {
 	account?: GoogleDriveAccount;
 	file?: GoogleDriveFile;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
index 4561cd9dd..ecac504da 100644
--- a/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/create-jira-issue.tsx
@@ -42,7 +42,7 @@ interface JiraPriority {
 	name: string;
 }
 
-interface CreateJiraIssueInterruptContext {
+type CreateJiraIssueInterruptContext = {
 	accounts?: JiraAccount[];
 	projects?: JiraProject[];
 	issue_types?: JiraIssueType[];
diff --git a/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
index cb8da37ea..99d84e023 100644
--- a/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/delete-jira-issue.tsx
@@ -25,7 +25,7 @@ interface JiraIssue {
 	document_id?: number;
 }
 
-interface DeleteJiraIssueInterruptContext {
+type DeleteJiraIssueInterruptContext = {
 	account?: JiraAccount;
 	issue?: JiraIssue;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx b/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
index 24643b542..dd9dbe123 100644
--- a/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
+++ b/surfsense_web/components/tool-ui/jira/update-jira-issue.tsx
@@ -45,7 +45,7 @@ interface JiraPriority {
 	name: string;
 }
 
-interface UpdateJiraIssueInterruptContext {
+type UpdateJiraIssueInterruptContext = {
 	account?: JiraAccount;
 	issue?: JiraIssue;
 	priorities?: JiraPriority[];
diff --git a/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
index 156cdb5ca..bbb5b0fef 100644
--- a/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
@@ -66,7 +66,7 @@ interface LinearWorkspace {
 	auth_expired?: boolean;
 }
 
-interface LinearCreateIssueContext {
+type LinearCreateIssueContext = {
 	workspaces?: LinearWorkspace[];
 	error?: string;
 }
diff --git a/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
index f033240de..67c9aa78c 100644
--- a/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
@@ -10,7 +10,7 @@ import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface LinearDeleteIssueContext {
+type LinearDeleteIssueContext = {
 	workspace?: { id: number; organization_name: string };
 	issue?: {
 		id: string;
diff --git a/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx b/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
index 4ff5b6e75..a03b605eb 100644
--- a/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
@@ -47,7 +47,7 @@ interface LinearPriority {
 	label: string;
 }
 
-interface LinearUpdateIssueContext {
+type LinearUpdateIssueContext = {
 	workspace?: { id: number; organization_name: string };
 	priorities?: LinearPriority[];
 	issue?: {
diff --git a/surfsense_web/components/tool-ui/notion/create-notion-page.tsx b/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
index 9a05dbc94..906b41c8a 100644
--- a/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/create-notion-page.tsx
@@ -19,7 +19,7 @@ import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface NotionCreatePageContext {
+type NotionCreatePageContext = {
 	accounts?: Array<{
 		id: number;
 		name: string;
diff --git a/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx b/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
index 5f30c7efd..7f3aa62af 100644
--- a/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/delete-notion-page.tsx
@@ -10,7 +10,7 @@ import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface NotionDeletePageContext {
+type NotionDeletePageContext = {
 	account?: {
 		id: number;
 		name: string;
diff --git a/surfsense_web/components/tool-ui/notion/update-notion-page.tsx b/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
index d07c6592b..c8221c586 100644
--- a/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
+++ b/surfsense_web/components/tool-ui/notion/update-notion-page.tsx
@@ -12,7 +12,7 @@ import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { isInterruptResult, useHitlDecision } from "@/lib/hitl";
 import type { InterruptResult, HitlDecision } from "@/lib/hitl";
 
-interface NotionUpdatePageContext {
+type NotionUpdatePageContext = {
 	account?: {
 		id: number;
 		name: string;
diff --git a/surfsense_web/components/tool-ui/onedrive/create-file.tsx b/surfsense_web/components/tool-ui/onedrive/create-file.tsx
index 502394986..285a873e7 100644
--- a/surfsense_web/components/tool-ui/onedrive/create-file.tsx
+++ b/surfsense_web/components/tool-ui/onedrive/create-file.tsx
@@ -26,7 +26,7 @@ interface OneDriveAccount {
 	auth_expired?: boolean;
 }
 
-interface OneDriveCreateFileContext {
+type OneDriveCreateFileContext = {
 	accounts?: OneDriveAccount[];
 	parent_folders?: Record<number, Array<{ folder_id: string; name: string }>>;
 	error?: string;
diff --git a/surfsense_web/components/tool-ui/onedrive/trash-file.tsx b/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
index 5735363c0..447022be2 100644
--- a/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
+++ b/surfsense_web/components/tool-ui/onedrive/trash-file.tsx
@@ -24,7 +24,7 @@ interface OneDriveFile {
 	web_url?: string;
 }
 
-interface OneDriveTrashFileContext {
+type OneDriveTrashFileContext = {
 	account?: OneDriveAccount;
 	file?: OneDriveFile;
 	error?: string;

From fce465a40ffb9f513f7f146cce4b0f1cdd4d0735 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 21:06:16 +0530
Subject: [PATCH 17/28] refactor: simplify layout structure in user settings
 components

---
 .../components/ProfileContent.tsx             |  2 +-
 .../settings/general-settings-manager.tsx     | 99 +++++++------------
 2 files changed, 39 insertions(+), 62 deletions(-)

diff --git a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/ProfileContent.tsx b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/ProfileContent.tsx
index c1e81283b..32377194a 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/ProfileContent.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/ProfileContent.tsx
@@ -78,7 +78,7 @@ export function ProfileContent() {
 				</div>
 			) : (
 				<form onSubmit={handleSubmit} className="space-y-6">
-					<div className="rounded-lg border bg-card p-6">
+					<div className="rounded-lg bg-card">
 						<div className="flex flex-col gap-6">
 							<div className="space-y-2">
 								<Label>{t("profile_avatar")}</Label>
diff --git a/surfsense_web/components/settings/general-settings-manager.tsx b/surfsense_web/components/settings/general-settings-manager.tsx
index e83525982..b8db34c38 100644
--- a/surfsense_web/components/settings/general-settings-manager.tsx
+++ b/surfsense_web/components/settings/general-settings-manager.tsx
@@ -9,7 +9,6 @@ import { toast } from "sonner";
 import { updateSearchSpaceMutationAtom } from "@/atoms/search-spaces/search-space-mutation.atoms";
 import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Skeleton } from "@/components/ui/skeleton";
@@ -83,16 +82,10 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 	if (loading) {
 		return (
 			<div className="space-y-4 md:space-y-6">
-				<Card>
-					<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
-						<Skeleton className="h-5 md:h-6 w-36 md:w-48" />
-						<Skeleton className="h-3 md:h-4 w-full max-w-md mt-2" />
-					</CardHeader>
-					<CardContent className="space-y-3 md:space-y-4 px-3 md:px-6 pb-3 md:pb-6">
-						<Skeleton className="h-10 md:h-12 w-full" />
-						<Skeleton className="h-10 md:h-12 w-full" />
-					</CardContent>
-				</Card>
+				<div className="flex flex-col gap-6">
+					<Skeleton className="h-10 md:h-12 w-full" />
+					<Skeleton className="h-10 md:h-12 w-full" />
+				</div>
 			</div>
 		);
 	}
@@ -113,61 +106,45 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 			<Alert className="bg-muted/50 py-3 md:py-4">
 				<Info className="h-3 w-3 md:h-4 md:w-4 shrink-0" />
 				<AlertDescription className="text-xs md:text-sm">
-					Update your search space name and description. These details help identify and organize
-					your workspace.
+					Update your search space name and description.
 				</AlertDescription>
 			</Alert>
 
-			{/* Search Space Details Card */}
-			<form onSubmit={onSubmit} className="space-y-4 md:space-y-6">
-				<Card>
-					<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
-						<CardTitle className="text-base md:text-lg">Search Space Details</CardTitle>
-						<CardDescription className="text-xs md:text-sm">
-							Manage the basic information for this search space.
-						</CardDescription>
-					</CardHeader>
-					<CardContent className="space-y-4 md:space-y-5 px-3 md:px-6 pb-3 md:pb-6">
-						<div className="space-y-1.5 md:space-y-2">
-							<Label htmlFor="search-space-name" className="text-sm md:text-base font-medium">
-								{t("general_name_label")}
-							</Label>
-							<Input
-								id="search-space-name"
-								placeholder={t("general_name_placeholder")}
-								value={name}
-								onChange={(e) => setName(e.target.value)}
-								className="text-sm md:text-base h-9 md:h-10"
-							/>
-							<p className="text-[10px] md:text-xs text-muted-foreground">
-								{t("general_name_description")}
-							</p>
-						</div>
+			<form onSubmit={onSubmit} className="space-y-6">
+				<div className="flex flex-col gap-6">
+					<div className="space-y-2">
+						<Label htmlFor="search-space-name">
+							{t("general_name_label")}
+						</Label>
+						<Input
+							id="search-space-name"
+							placeholder={t("general_name_placeholder")}
+							value={name}
+							onChange={(e) => setName(e.target.value)}
+						/>
+						<p className="text-xs text-muted-foreground">
+							{t("general_name_description")}
+						</p>
+					</div>
 
-						<div className="space-y-1.5 md:space-y-2">
-							<Label
-								htmlFor="search-space-description"
-								className="text-sm md:text-base font-medium"
-							>
-								{t("general_description_label")}{" "}
-								<span className="text-muted-foreground font-normal">({tCommon("optional")})</span>
-							</Label>
-							<Input
-								id="search-space-description"
-								placeholder={t("general_description_placeholder")}
-								value={description}
-								onChange={(e) => setDescription(e.target.value)}
-								className="text-sm md:text-base h-9 md:h-10"
-							/>
-							<p className="text-[10px] md:text-xs text-muted-foreground">
-								{t("general_description_description")}
-							</p>
-						</div>
-					</CardContent>
-				</Card>
+					<div className="space-y-2">
+						<Label htmlFor="search-space-description">
+							{t("general_description_label")}{" "}
+							<span className="text-muted-foreground font-normal">({tCommon("optional")})</span>
+						</Label>
+						<Input
+							id="search-space-description"
+							placeholder={t("general_description_placeholder")}
+							value={description}
+							onChange={(e) => setDescription(e.target.value)}
+						/>
+						<p className="text-xs text-muted-foreground">
+							{t("general_description_description")}
+						</p>
+					</div>
+				</div>
 
-				{/* Action Buttons */}
-				<div className="flex justify-end pt-3 md:pt-4">
+				<div className="flex justify-end">
 					<Button
 						type="submit"
 						variant="outline"

From b6e2510e55adc0508fea0f904c04add46bf63dd6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 21:25:17 +0530
Subject: [PATCH 18/28] refactor: remove export functionality from
 DocumentsFilters and streamline DocumentsSidebar export handling

---
 .../components/documents/DocumentsFilters.tsx | 35 +------
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 92 ++++---------------
 .../settings/general-settings-manager.tsx     | 57 +++++++++++-
 3 files changed, 78 insertions(+), 106 deletions(-)

diff --git a/surfsense_web/components/documents/DocumentsFilters.tsx b/surfsense_web/components/documents/DocumentsFilters.tsx
index 703c9c3b4..d43f3680b 100644
--- a/surfsense_web/components/documents/DocumentsFilters.tsx
+++ b/surfsense_web/components/documents/DocumentsFilters.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Download, FolderPlus, ListFilter, Loader2, Search, Upload, X } from "lucide-react";
+import { FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { useCallback, useMemo, useRef, useState } from "react";
 import { useDocumentUploadDialog } from "@/components/assistant-ui/document-upload-popup";
@@ -20,8 +20,6 @@ export function DocumentsFilters({
 	onToggleType,
 	activeTypes,
 	onCreateFolder,
-	onExportKB,
-	isExporting,
 }: {
 	typeCounts: Partial<Record<DocumentTypeEnum, number>>;
 	onSearch: (v: string) => void;
@@ -29,8 +27,6 @@ export function DocumentsFilters({
 	onToggleType: (type: DocumentTypeEnum, checked: boolean) => void;
 	activeTypes: DocumentTypeEnum[];
 	onCreateFolder?: () => void;
-	onExportKB?: () => void;
-	isExporting?: boolean;
 }) {
 	const t = useTranslations("documents");
 	const id = React.useId();
@@ -85,33 +81,8 @@ export function DocumentsFilters({
 								</ToggleGroupItem>
 							</TooltipTrigger>
 							<TooltipContent>New folder</TooltipContent>
-						</Tooltip>
-					)}
-
-					{onExportKB && (
-						<Tooltip>
-							<TooltipTrigger asChild>
-								<ToggleGroupItem
-									value="export"
-									disabled={isExporting}
-									className="h-9 w-9 shrink-0 border-sidebar-border text-sidebar-foreground/60 hover:text-sidebar-foreground hover:border-sidebar-border bg-sidebar"
-									onClick={(e) => {
-										e.preventDefault();
-										onExportKB();
-									}}
-								>
-									{isExporting ? (
-										<Loader2 size={14} className="animate-spin" />
-									) : (
-										<Download size={14} />
-									)}
-								</ToggleGroupItem>
-							</TooltipTrigger>
-							<TooltipContent>
-								{isExporting ? "Exporting…" : "Export knowledge base"}
-							</TooltipContent>
-						</Tooltip>
-					)}
+					</Tooltip>
+				)}
 
 					<Popover>
 						<Tooltip>
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 20b25a2d2..95bd21e3b 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -406,22 +406,13 @@ export function DocumentsSidebar({
 		setFolderPickerOpen(true);
 	}, []);
 
-	const [isExportingKB, setIsExportingKB] = useState(false);
+	const [, setIsExportingKB] = useState(false);
 	const [exportWarningOpen, setExportWarningOpen] = useState(false);
 	const [exportWarningContext, setExportWarningContext] = useState<{
-		type: "kb" | "folder";
-		folder?: FolderDisplay;
+		folder: FolderDisplay;
 		pendingCount: number;
 	} | null>(null);
 
-	const pendingDocuments = useMemo(
-		() =>
-			treeDocuments.filter(
-				(d) => d.status?.state === "pending" || d.status?.state === "processing"
-			),
-		[treeDocuments]
-	);
-
 	const doExport = useCallback(async (url: string, downloadName: string) => {
 		const response = await authenticatedFetch(url, { method: "GET" });
 		if (!response.ok) {
@@ -440,68 +431,28 @@ export function DocumentsSidebar({
 		URL.revokeObjectURL(blobUrl);
 	}, []);
 
-	const handleExportKB = useCallback(async () => {
-		if (isExportingKB) return;
-
-		if (pendingDocuments.length > 0) {
-			setExportWarningContext({ type: "kb", pendingCount: pendingDocuments.length });
-			setExportWarningOpen(true);
-			return;
-		}
-
-		setIsExportingKB(true);
-		try {
-			await doExport(
-				`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/export`,
-				"knowledge-base.zip"
-			);
-			toast.success("Knowledge base exported");
-		} catch (err) {
-			console.error("KB export failed:", err);
-			toast.error(err instanceof Error ? err.message : "Export failed");
-		} finally {
-			setIsExportingKB(false);
-		}
-	}, [searchSpaceId, isExportingKB, pendingDocuments.length, doExport]);
-
 	const handleExportWarningConfirm = useCallback(async () => {
 		setExportWarningOpen(false);
 		const ctx = exportWarningContext;
-		if (!ctx) return;
+		if (!ctx?.folder) return;
 
-		if (ctx.type === "kb") {
-			setIsExportingKB(true);
-			try {
-				await doExport(
-					`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/export`,
-					"knowledge-base.zip"
-				);
-				toast.success("Knowledge base exported");
-			} catch (err) {
-				console.error("KB export failed:", err);
-				toast.error(err instanceof Error ? err.message : "Export failed");
-			} finally {
-				setIsExportingKB(false);
-			}
-		} else if (ctx.type === "folder" && ctx.folder) {
-			setIsExportingKB(true);
-			try {
-				const safeName =
-					ctx.folder.name
-						.replace(/[^a-zA-Z0-9 _-]/g, "_")
-						.trim()
-						.slice(0, 80) || "folder";
-				await doExport(
-					`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/export?folder_id=${ctx.folder.id}`,
-					`${safeName}.zip`
-				);
-				toast.success(`Folder "${ctx.folder.name}" exported`);
-			} catch (err) {
-				console.error("Folder export failed:", err);
-				toast.error(err instanceof Error ? err.message : "Export failed");
-			} finally {
-				setIsExportingKB(false);
-			}
+		setIsExportingKB(true);
+		try {
+			const safeName =
+				ctx.folder.name
+					.replace(/[^a-zA-Z0-9 _-]/g, "_")
+					.trim()
+					.slice(0, 80) || "folder";
+			await doExport(
+				`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/export?folder_id=${ctx.folder.id}`,
+				`${safeName}.zip`
+			);
+			toast.success(`Folder "${ctx.folder.name}" exported`);
+		} catch (err) {
+			console.error("Folder export failed:", err);
+			toast.error(err instanceof Error ? err.message : "Export failed");
+		} finally {
+			setIsExportingKB(false);
 		}
 		setExportWarningContext(null);
 	}, [exportWarningContext, searchSpaceId, doExport]);
@@ -530,7 +481,6 @@ export function DocumentsSidebar({
 			const folderPendingCount = getPendingCountInSubtree(folder.id);
 			if (folderPendingCount > 0) {
 				setExportWarningContext({
-					type: "folder",
 					folder,
 					pendingCount: folderPendingCount,
 				});
@@ -954,8 +904,6 @@ export function DocumentsSidebar({
 						onToggleType={onToggleType}
 						activeTypes={activeTypes}
 						onCreateFolder={() => handleCreateFolder(null)}
-						onExportKB={handleExportKB}
-						isExporting={isExportingKB}
 					/>
 				</div>
 
diff --git a/surfsense_web/components/settings/general-settings-manager.tsx b/surfsense_web/components/settings/general-settings-manager.tsx
index b8db34c38..99fa02f0d 100644
--- a/surfsense_web/components/settings/general-settings-manager.tsx
+++ b/surfsense_web/components/settings/general-settings-manager.tsx
@@ -2,9 +2,9 @@
 
 import { useQuery } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
-import { Info } from "lucide-react";
+import { FolderArchive, Info } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { toast } from "sonner";
 import { updateSearchSpaceMutationAtom } from "@/atoms/search-spaces/search-space-mutation.atoms";
 import { Alert, AlertDescription } from "@/components/ui/alert";
@@ -13,6 +13,7 @@ import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Skeleton } from "@/components/ui/skeleton";
 import { searchSpacesApiService } from "@/lib/apis/search-spaces-api.service";
+import { authenticatedFetch } from "@/lib/auth-utils";
 import { cacheKeys } from "@/lib/query-client/cache-keys";
 import { Spinner } from "../ui/spinner";
 
@@ -39,6 +40,37 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 	const [name, setName] = useState("");
 	const [description, setDescription] = useState("");
 	const [saving, setSaving] = useState(false);
+	const [isExporting, setIsExporting] = useState(false);
+
+	const handleExportKB = useCallback(async () => {
+		if (isExporting) return;
+		setIsExporting(true);
+		try {
+			const response = await authenticatedFetch(
+				`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/export`,
+				{ method: "GET" }
+			);
+			if (!response.ok) {
+				const errorData = await response.json().catch(() => ({ detail: "Export failed" }));
+				throw new Error(errorData.detail || "Export failed");
+			}
+			const blob = await response.blob();
+			const url = URL.createObjectURL(blob);
+			const a = document.createElement("a");
+			a.href = url;
+			a.download = "knowledge-base.zip";
+			document.body.appendChild(a);
+			a.click();
+			document.body.removeChild(a);
+			URL.revokeObjectURL(url);
+			toast.success("Knowledge base exported");
+		} catch (err) {
+			console.error("KB export failed:", err);
+			toast.error(err instanceof Error ? err.message : "Export failed");
+		} finally {
+			setIsExporting(false);
+		}
+	}, [searchSpaceId, isExporting]);
 
 	// Initialize state from fetched search space
 	useEffect(() => {
@@ -156,6 +188,27 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 					</Button>
 				</div>
 			</form>
+
+			<div className="border-t pt-6 space-y-2">
+				<Label>Export knowledge base</Label>
+				<p className="text-xs text-muted-foreground">
+					Download all documents in this search space as a ZIP of markdown files.
+				</p>
+				<Button
+					type="button"
+					variant="secondary"
+					size="sm"
+					disabled={isExporting}
+					onClick={handleExportKB}
+					className="relative"
+				>
+					<span className={isExporting ? "opacity-0" : ""}>
+						<FolderArchive className="h-3 w-3 opacity-60" />
+					</span>
+					<span className={isExporting ? "opacity-0" : ""}>Export</span>
+					{isExporting && <Spinner size="sm" className="absolute" />}
+				</Button>
+			</div>
 		</div>
 	);
 }

From 25644e1c0b32e137b054530e7b9667644dcdc7ac Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 21:36:07 +0530
Subject: [PATCH 19/28] refactor: replace Eye icon with ScanEye in multiple
 components and enhance model not found messages

---
 .../components/new-chat/model-selector.tsx    | 42 +++++++++++++------
 .../components/settings/llm-role-manager.tsx  |  4 +-
 .../settings/search-space-settings-dialog.tsx |  4 +-
 3 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/surfsense_web/components/new-chat/model-selector.tsx b/surfsense_web/components/new-chat/model-selector.tsx
index ec5bf6760..00e37491d 100644
--- a/surfsense_web/components/new-chat/model-selector.tsx
+++ b/surfsense_web/components/new-chat/model-selector.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { Bot, Check, ChevronDown, Edit3, Eye, ImageIcon, Plus, Search, Zap } from "lucide-react";
+import { Bot, Check, ChevronDown, Edit3, ImageIcon, Plus, ScanEye, Search, Zap } from "lucide-react";
 import { type UIEvent, useCallback, useMemo, useState } from "react";
 import { toast } from "sonner";
 import {
@@ -387,7 +387,7 @@ export function ModelSelector({
 									</span>
 								</>
 							) : (
-								<Eye className="size-4 text-muted-foreground" />
+								<ScanEye className="size-4 text-muted-foreground" />
 							)}
 						</>
 					)}
@@ -425,7 +425,7 @@ export function ModelSelector({
 								value="vision"
 								className="gap-1.5 text-sm font-medium rounded-none text-muted-foreground transition-all duration-200 h-full bg-transparent data-[state=active]:bg-transparent shadow-none data-[state=active]:shadow-none border-b-[1.5px] border-transparent data-[state=active]:border-foreground dark:data-[state=active]:border-white data-[state=active]:text-foreground"
 							>
-								<Eye className="size-3.5" />
+								<ScanEye className="size-3.5" />
 								Vision
 							</TabsTrigger>
 						</TabsList>
@@ -458,9 +458,15 @@ export function ModelSelector({
 							>
 								<CommandEmpty className="py-8 text-center">
 									<div className="flex flex-col items-center gap-2">
-										<Search className="size-8 text-muted-foreground" />
-										<p className="text-sm text-muted-foreground">No models found</p>
-										<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+										{llmGlobalConfigs?.length || llmUserConfigs?.length ? (
+											<>
+												<Search className="size-8 text-muted-foreground" />
+												<p className="text-sm text-muted-foreground">No models found</p>
+												<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+											</>
+										) : (
+											<p className="text-sm text-muted-foreground">No models found</p>
+										)}
 									</div>
 								</CommandEmpty>
 
@@ -645,9 +651,15 @@ export function ModelSelector({
 							>
 								<CommandEmpty className="py-8 text-center">
 									<div className="flex flex-col items-center gap-2">
-										<Search className="size-8 text-muted-foreground" />
-										<p className="text-sm text-muted-foreground">No image models found</p>
-										<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+										{imageGlobalConfigs?.length || imageUserConfigs?.length ? (
+											<>
+												<Search className="size-8 text-muted-foreground" />
+												<p className="text-sm text-muted-foreground">No image models found</p>
+												<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+											</>
+										) : (
+											<p className="text-sm text-muted-foreground">No image models found</p>
+										)}
 									</div>
 								</CommandEmpty>
 
@@ -817,9 +829,15 @@ export function ModelSelector({
 							>
 								<CommandEmpty className="py-8 text-center">
 									<div className="flex flex-col items-center gap-2">
-										<Search className="size-8 text-muted-foreground" />
-										<p className="text-sm text-muted-foreground">No vision models found</p>
-										<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+										{visionGlobalConfigs?.length || visionUserConfigs?.length ? (
+											<>
+												<Search className="size-8 text-muted-foreground" />
+												<p className="text-sm text-muted-foreground">No vision models found</p>
+												<p className="text-xs text-muted-foreground/60">Try a different search term</p>
+											</>
+										) : (
+											<p className="text-sm text-muted-foreground">No vision models found</p>
+										)}
 									</div>
 								</CommandEmpty>
 
diff --git a/surfsense_web/components/settings/llm-role-manager.tsx b/surfsense_web/components/settings/llm-role-manager.tsx
index e280db493..d6eb7c64d 100644
--- a/surfsense_web/components/settings/llm-role-manager.tsx
+++ b/surfsense_web/components/settings/llm-role-manager.tsx
@@ -6,7 +6,7 @@ import {
 	Bot,
 	CircleCheck,
 	CircleDashed,
-	Eye,
+	ScanEye,
 	FileText,
 	ImageIcon,
 	RefreshCw,
@@ -74,7 +74,7 @@ const ROLE_DESCRIPTIONS = {
 		configType: "image" as const,
 	},
 	vision: {
-		icon: Eye,
+		icon: ScanEye,
 		title: "Vision LLM",
 		description: "Vision-capable model for screenshot analysis and context extraction",
 		color: "text-muted-foreground",
diff --git a/surfsense_web/components/settings/search-space-settings-dialog.tsx b/surfsense_web/components/settings/search-space-settings-dialog.tsx
index 56ad0ab8f..4469addf4 100644
--- a/surfsense_web/components/settings/search-space-settings-dialog.tsx
+++ b/surfsense_web/components/settings/search-space-settings-dialog.tsx
@@ -7,7 +7,7 @@ import {
 	Brain,
 	CircleUser,
 	Earth,
-	Eye,
+	ScanEye,
 	ImageIcon,
 	ListChecks,
 	UserKey,
@@ -97,7 +97,7 @@ export function SearchSpaceSettingsDialog({ searchSpaceId }: SearchSpaceSettings
 		{
 			value: "vision-models",
 			label: t("nav_vision_models"),
-			icon: <Eye className="h-4 w-4" />,
+			icon: <ScanEye className="h-4 w-4" />,
 		},
 		{ value: "team-roles", label: t("nav_team_roles"), icon: <UserKey className="h-4 w-4" /> },
 		{

From 635cdde0ebc02988a2c1ac5d4c2c83e26c9733c0 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 21:45:53 +0530
Subject: [PATCH 20/28] refactor: enhance roles manager component with expanded
 role details and improved permissions display

---
 .../components/settings/roles-manager.tsx     | 407 +++++++++---------
 1 file changed, 199 insertions(+), 208 deletions(-)

diff --git a/surfsense_web/components/settings/roles-manager.tsx b/surfsense_web/components/settings/roles-manager.tsx
index 5b30b5f60..b72a53854 100644
--- a/surfsense_web/components/settings/roles-manager.tsx
+++ b/surfsense_web/components/settings/roles-manager.tsx
@@ -4,6 +4,7 @@ import { useQuery } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import {
 	Bot,
+	ChevronDown,
 	Edit2,
 	FileText,
 	Globe,
@@ -47,7 +48,6 @@ import {
 	DialogDescription,
 	DialogHeader,
 	DialogTitle,
-	DialogTrigger,
 } from "@/components/ui/dialog";
 import {
 	DropdownMenu,
@@ -58,7 +58,6 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
-import { ScrollArea } from "@/components/ui/scroll-area";
 import { Spinner } from "@/components/ui/spinner";
 import type { PermissionInfo } from "@/contracts/types/permissions.types";
 import type {
@@ -319,100 +318,6 @@ export function RolesManager({ searchSpaceId }: { searchSpaceId: number }) {
 	);
 }
 
-// ============ Role Permissions Display ============
-
-function RolePermissionsDialog({
-	permissions,
-	roleName,
-	children,
-}: {
-	permissions: string[];
-	roleName: string;
-	children: React.ReactNode;
-}) {
-	const isFullAccess = permissions.includes("*");
-
-	const grouped: Record<string, string[]> = {};
-	if (!isFullAccess) {
-		for (const perm of permissions) {
-			const [category, action] = perm.split(":");
-			if (!grouped[category]) grouped[category] = [];
-			grouped[category].push(action);
-		}
-	}
-
-	const sortedCategories = Object.keys(grouped).sort((a, b) => {
-		const orderA = CATEGORY_CONFIG[a]?.order ?? 99;
-		const orderB = CATEGORY_CONFIG[b]?.order ?? 99;
-		return orderA - orderB;
-	});
-
-	const categoryCount = sortedCategories.length;
-
-	return (
-		<Dialog>
-			<DialogTrigger asChild>{children}</DialogTrigger>
-			<DialogContent className="w-[92vw] max-w-md p-0 gap-0">
-				<DialogHeader className="p-4 md:p-5">
-					<DialogTitle className="text-base">{roleName} — Permissions</DialogTitle>
-					<DialogDescription className="text-xs">
-						{isFullAccess
-							? "This role has unrestricted access to all resources"
-							: `${permissions.length} permissions across ${categoryCount} categories`}
-					</DialogDescription>
-				</DialogHeader>
-				{isFullAccess ? (
-					<div className="flex items-center gap-3 px-4 md:px-5 py-6">
-						<div className="h-9 w-9 rounded-lg bg-muted/60 flex items-center justify-center shrink-0">
-							<Shield className="h-4 w-4 text-muted-foreground" />
-						</div>
-						<div>
-							<p className="text-sm font-medium">Full access</p>
-							<p className="text-xs text-muted-foreground">
-								All permissions granted across every category
-							</p>
-						</div>
-					</div>
-				) : (
-					<ScrollArea className="max-h-[55vh]">
-						<div className="divide-y divide-border/50">
-							{sortedCategories.map((category) => {
-								const actions = grouped[category];
-								const config = CATEGORY_CONFIG[category] || {
-									label: category,
-									icon: FileText,
-								};
-								const IconComponent = config.icon;
-								return (
-									<div
-										key={category}
-										className="flex items-center justify-between gap-3 px-4 md:px-5 py-2.5"
-									>
-										<div className="flex items-center gap-2 shrink-0">
-											<IconComponent className="h-3.5 w-3.5 text-muted-foreground" />
-											<span className="text-sm text-muted-foreground">{config.label}</span>
-										</div>
-										<div className="flex flex-wrap justify-end gap-1">
-											{actions.map((action) => (
-												<span
-													key={action}
-													className="px-1.5 py-0.5 rounded bg-muted text-muted-foreground text-[11px] font-medium"
-												>
-													{ACTION_LABELS[action] || action.replace(/_/g, " ")}
-												</span>
-											))}
-										</div>
-									</div>
-								);
-							})}
-						</div>
-					</ScrollArea>
-				)}
-			</DialogContent>
-		</Dialog>
-	);
-}
-
 function PermissionsBadge({ permissions }: { permissions: string[] }) {
 	if (permissions.includes("*")) {
 		return (
@@ -463,6 +368,7 @@ function RolesContent({
 }) {
 	const [showCreateRole, setShowCreateRole] = useState(false);
 	const [editingRoleId, setEditingRoleId] = useState<number | null>(null);
+	const [expandedRoleId, setExpandedRoleId] = useState<number | null>(null);
 
 	if (loading) {
 		return (
@@ -508,91 +414,170 @@ function RolesContent({
 			)}
 
 			<div className="space-y-3">
-				{roles.map((role) => (
-					<div key={role.id}>
-						<div className="w-full text-left relative flex items-center gap-4 rounded-lg border border-border/60 p-4 transition-colors hover:bg-muted/30">
-							<div className="flex-1 min-w-0">
-								<RolePermissionsDialog permissions={role.permissions} roleName={role.name}>
-									<button type="button" className="w-full text-left cursor-pointer">
-										<div className="flex items-center gap-2">
-											<span className="font-medium text-sm">{role.name}</span>
-											{role.is_system_role && (
-												<span className="text-[10px] px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-medium">
-													System
-												</span>
-											)}
-											{role.is_default && (
-												<span className="text-[10px] px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-medium">
-													Default
-												</span>
-											)}
-										</div>
-										{role.description && (
-											<p className="text-xs text-muted-foreground mt-0.5 truncate">
-												{role.description}
-											</p>
+				{roles.map((role) => {
+					const isExpanded = expandedRoleId === role.id;
+					const isFullAccess = role.permissions.includes("*");
+
+					const grouped: Record<string, string[]> = {};
+					if (!isFullAccess) {
+						for (const perm of role.permissions) {
+							const [category, action] = perm.split(":");
+							if (!grouped[category]) grouped[category] = [];
+							grouped[category].push(action);
+						}
+					}
+					const sortedCategories = Object.keys(grouped).sort((a, b) => {
+						const orderA = CATEGORY_CONFIG[a]?.order ?? 99;
+						const orderB = CATEGORY_CONFIG[b]?.order ?? 99;
+						return orderA - orderB;
+					});
+
+					return (
+						<div key={role.id} className="rounded-lg border border-border/60 overflow-hidden">
+							<div className="flex items-center gap-4 p-4 transition-colors hover:bg-muted/30">
+								<button
+									type="button"
+									className="flex-1 min-w-0 text-left cursor-pointer"
+									onClick={() => setExpandedRoleId(isExpanded ? null : role.id)}
+								>
+									<div className="flex items-center gap-2">
+										<span className="font-medium text-sm">{role.name}</span>
+										{role.is_system_role && (
+											<span className="text-[10px] px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-medium">
+												System
+											</span>
 										)}
-									</button>
-								</RolePermissionsDialog>
+										{role.is_default && (
+											<span className="text-[10px] px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-medium">
+												Default
+											</span>
+										)}
+									</div>
+									{role.description && (
+										<p className="text-xs text-muted-foreground mt-0.5 truncate">
+											{role.description}
+										</p>
+									)}
+								</button>
+
+								<div className="shrink-0">
+									<PermissionsBadge permissions={role.permissions} />
+								</div>
+
+								{!role.is_system_role && (
+									<div className="shrink-0" role="none">
+										<DropdownMenu>
+											<DropdownMenuTrigger asChild>
+												<Button variant="ghost" size="icon" className="h-8 w-8">
+													<MoreHorizontal className="h-4 w-4" />
+												</Button>
+											</DropdownMenuTrigger>
+											<DropdownMenuContent align="end" onCloseAutoFocus={(e) => e.preventDefault()}>
+												{canUpdate && (
+													<DropdownMenuItem onClick={() => setEditingRoleId(role.id)}>
+														<Edit2 className="h-4 w-4 mr-2" />
+														Edit Role
+													</DropdownMenuItem>
+												)}
+												{canDelete && (
+													<>
+														<DropdownMenuSeparator />
+														<AlertDialog>
+															<AlertDialogTrigger asChild>
+																<DropdownMenuItem onSelect={(e) => e.preventDefault()}>
+																	<Trash2 className="h-4 w-4 mr-2" />
+																	Delete Role
+																</DropdownMenuItem>
+															</AlertDialogTrigger>
+															<AlertDialogContent>
+																<AlertDialogHeader>
+																	<AlertDialogTitle>Delete role?</AlertDialogTitle>
+																	<AlertDialogDescription>
+																		This will permanently delete the &quot;{role.name}&quot; role.
+																		Members with this role will lose their permissions.
+																	</AlertDialogDescription>
+																</AlertDialogHeader>
+																<AlertDialogFooter>
+																	<AlertDialogCancel>Cancel</AlertDialogCancel>
+																	<AlertDialogAction
+																		onClick={() => onDeleteRole(role.id)}
+																		className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+																	>
+																		Delete
+																	</AlertDialogAction>
+																</AlertDialogFooter>
+															</AlertDialogContent>
+														</AlertDialog>
+													</>
+												)}
+											</DropdownMenuContent>
+										</DropdownMenu>
+									</div>
+								)}
+
+								<button
+									type="button"
+									className="shrink-0 p-1 cursor-pointer"
+									onClick={() => setExpandedRoleId(isExpanded ? null : role.id)}
+								>
+									<ChevronDown
+										className={cn(
+											"h-4 w-4 text-muted-foreground transition-transform duration-200",
+											isExpanded && "rotate-180"
+										)}
+									/>
+								</button>
 							</div>
 
-							<div className="shrink-0">
-								<PermissionsBadge permissions={role.permissions} />
-							</div>
-
-							{!role.is_system_role && (
-								<div className="shrink-0" role="none">
-									<DropdownMenu>
-										<DropdownMenuTrigger asChild>
-											<Button variant="ghost" size="icon" className="h-8 w-8">
-												<MoreHorizontal className="h-4 w-4" />
-											</Button>
-										</DropdownMenuTrigger>
-										<DropdownMenuContent align="end" onCloseAutoFocus={(e) => e.preventDefault()}>
-											{canUpdate && (
-												<DropdownMenuItem onClick={() => setEditingRoleId(role.id)}>
-													<Edit2 className="h-4 w-4 mr-2" />
-													Edit Role
-												</DropdownMenuItem>
-											)}
-											{canDelete && (
-												<>
-													<DropdownMenuSeparator />
-													<AlertDialog>
-														<AlertDialogTrigger asChild>
-															<DropdownMenuItem onSelect={(e) => e.preventDefault()}>
-																<Trash2 className="h-4 w-4 mr-2" />
-																Delete Role
-															</DropdownMenuItem>
-														</AlertDialogTrigger>
-														<AlertDialogContent>
-															<AlertDialogHeader>
-																<AlertDialogTitle>Delete role?</AlertDialogTitle>
-																<AlertDialogDescription>
-																	This will permanently delete the &quot;{role.name}&quot; role.
-																	Members with this role will lose their permissions.
-																</AlertDialogDescription>
-															</AlertDialogHeader>
-															<AlertDialogFooter>
-																<AlertDialogCancel>Cancel</AlertDialogCancel>
-																<AlertDialogAction
-																	onClick={() => onDeleteRole(role.id)}
-																	className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+							{isExpanded && (
+								<div className="border-t border-border/40 px-4 py-3">
+									{isFullAccess ? (
+										<div className="flex items-center gap-3 py-2">
+											<Shield className="h-4 w-4 text-muted-foreground shrink-0" />
+											<p className="text-sm text-muted-foreground">
+												Full access — all permissions granted across every category
+											</p>
+										</div>
+									) : (
+										<div className="divide-y divide-border/30">
+											{sortedCategories.map((category) => {
+												const actions = grouped[category];
+												const config = CATEGORY_CONFIG[category] || {
+													label: category,
+													icon: FileText,
+												};
+												const IconComponent = config.icon;
+												return (
+													<div
+														key={category}
+														className="flex items-center justify-between gap-3 py-2.5"
+													>
+														<div className="flex items-center gap-2 shrink-0">
+															<IconComponent className="h-3.5 w-3.5 text-muted-foreground" />
+															<span className="text-sm text-muted-foreground">
+																{config.label}
+															</span>
+														</div>
+														<div className="flex flex-wrap justify-end gap-1">
+															{actions.map((action) => (
+																<span
+																	key={action}
+																	className="px-1.5 py-0.5 rounded bg-muted text-muted-foreground text-[11px] font-medium"
 																>
-																	Delete
-																</AlertDialogAction>
-															</AlertDialogFooter>
-														</AlertDialogContent>
-													</AlertDialog>
-												</>
-											)}
-										</DropdownMenuContent>
-									</DropdownMenu>
+																	{ACTION_LABELS[action] || action.replace(/_/g, " ")}
+																</span>
+															))}
+														</div>
+													</div>
+												);
+											})}
+										</div>
+									)}
 								</div>
 							)}
 						</div>
-					</div>
-				))}
+					);
+				})}
 			</div>
 		</div>
 	);
@@ -676,46 +661,51 @@ function PermissionsEditor({
 
 					return (
 						<div key={category} className="rounded-lg border border-border/60 overflow-hidden">
-							<button
-								type="button"
-								className="w-full flex items-center justify-between px-3 py-2.5 cursor-pointer hover:bg-muted/40 transition-colors"
-								onClick={() => toggleCategoryExpanded(category)}
-							>
-								<div className="flex items-center gap-2.5">
+							<div className="flex items-center justify-between px-3 py-2.5 hover:bg-muted/40 transition-colors">
+								<button
+									type="button"
+									className="flex-1 flex items-center gap-2.5 cursor-pointer"
+									onClick={() => toggleCategoryExpanded(category)}
+								>
 									<IconComponent className="h-4 w-4 text-muted-foreground shrink-0" />
 									<span className="font-medium text-sm">{config.label}</span>
 									<span className="text-[11px] text-muted-foreground tabular-nums">
 										{stats.selected}/{stats.total}
 									</span>
-								</div>
+								</button>
 								<div className="flex items-center gap-2">
 									<Checkbox
 										checked={stats.allSelected}
 										onCheckedChange={() => onToggleCategory(category)}
-										onClick={(e) => e.stopPropagation()}
 										aria-label={`Select all ${config.label} permissions`}
 									/>
-									<div
-										className={cn("transition-transform duration-200", isExpanded && "rotate-180")}
+									<button
+										type="button"
+										className="cursor-pointer"
+										onClick={() => toggleCategoryExpanded(category)}
 									>
-										<svg
-											className="h-4 w-4 text-muted-foreground"
-											fill="none"
-											viewBox="0 0 24 24"
-											stroke="currentColor"
-											aria-hidden="true"
+										<div
+											className={cn("transition-transform duration-200", isExpanded && "rotate-180")}
 										>
-											<title>Toggle</title>
-											<path
-												strokeLinecap="round"
-												strokeLinejoin="round"
-												strokeWidth={2}
-												d="M19 9l-7 7-7-7"
-											/>
-										</svg>
-									</div>
+											<svg
+												className="h-4 w-4 text-muted-foreground"
+												fill="none"
+												viewBox="0 0 24 24"
+												stroke="currentColor"
+												aria-hidden="true"
+											>
+												<title>Toggle</title>
+												<path
+													strokeLinecap="round"
+													strokeLinejoin="round"
+													strokeWidth={2}
+													d="M19 9l-7 7-7-7"
+												/>
+											</svg>
+										</div>
+									</button>
 								</div>
-							</button>
+							</div>
 
 							{isExpanded && (
 								<div className="border-t border-border/60">
@@ -726,28 +716,29 @@ function PermissionsEditor({
 											const isSelected = selectedPermissions.includes(perm.value);
 
 											return (
-												<button
+												<div
 													key={perm.value}
-													type="button"
 													className={cn(
-														"w-full flex items-center justify-between gap-3 px-2.5 py-2 rounded-md cursor-pointer transition-colors",
+														"flex items-center justify-between gap-3 px-2.5 py-2 rounded-md transition-colors",
 														isSelected ? "bg-muted/60 hover:bg-muted/80" : "hover:bg-muted/40"
 													)}
-													onClick={() => onTogglePermission(perm.value)}
 												>
-													<div className="flex-1 min-w-0 text-left">
+													<button
+														type="button"
+														className="flex-1 min-w-0 text-left cursor-pointer"
+														onClick={() => onTogglePermission(perm.value)}
+													>
 														<span className="text-sm font-medium">{actionLabel}</span>
 														<p className="text-xs text-muted-foreground truncate">
 															{perm.description}
 														</p>
-													</div>
+													</button>
 													<Checkbox
 														checked={isSelected}
 														onCheckedChange={() => onTogglePermission(perm.value)}
-														onClick={(e) => e.stopPropagation()}
 														className="shrink-0"
 													/>
-												</button>
+												</div>
 											);
 										})}
 									</div>

From ec2780764493c89c5d7cf9819baba7c51e3c817b Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Mon, 13 Apr 2026 22:22:50 +0530
Subject: [PATCH 21/28] refactor: improve document processing error handling
 and UI state management

---
 surfsense_backend/app/routes/editor_routes.py |  12 +-
 .../components/documents/DocumentNode.tsx     | 130 +++++++++---------
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |   7 +-
 3 files changed, 80 insertions(+), 69 deletions(-)

diff --git a/surfsense_backend/app/routes/editor_routes.py b/surfsense_backend/app/routes/editor_routes.py
index 829b2cf69..0f986e416 100644
--- a/surfsense_backend/app/routes/editor_routes.py
+++ b/surfsense_backend/app/routes/editor_routes.py
@@ -139,9 +139,19 @@ async def get_editor_content(
                 status_code=409,
                 detail="This document is still being processed. Please wait a moment and try again.",
             )
+        if state == "failed":
+            reason = (
+                doc_status.get("reason", "Unknown error")
+                if isinstance(doc_status, dict)
+                else "Unknown error"
+            )
+            raise HTTPException(
+                status_code=422,
+                detail=f"Processing failed: {reason}. You can delete this document and re-upload it.",
+            )
         raise HTTPException(
             status_code=400,
-            detail="This document has no viewable content yet. It may still be syncing. Try again in a few seconds, or re-upload if the issue persists.",
+            detail="This document has no content. It may not have been processed correctly. Try deleting and re-uploading it.",
         )
 
     markdown_content = "\n\n".join(chunk_contents)
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index 04cec5f89..478037520 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -82,11 +82,12 @@ export const DocumentNode = React.memo(function DocumentNode({
 	onContextMenuOpenChange,
 }: DocumentNodeProps) {
 	const statusState = doc.status?.state ?? "ready";
-	const isSelectable = statusState !== "pending" && statusState !== "processing";
+	const isFailed = statusState === "failed";
+	const isProcessing = statusState === "pending" || statusState === "processing";
+	const isUnavailable = isProcessing || isFailed;
+	const isSelectable = !isUnavailable;
 	const isEditable =
-		EDITABLE_DOCUMENT_TYPES.has(doc.document_type) &&
-		statusState !== "pending" &&
-		statusState !== "processing";
+		EDITABLE_DOCUMENT_TYPES.has(doc.document_type) && !isUnavailable;
 
 	const handleCheckChange = useCallback(() => {
 		if (isSelectable) {
@@ -103,7 +104,6 @@ export const DocumentNode = React.memo(function DocumentNode({
 		[doc.id]
 	);
 
-	const isProcessing = statusState === "pending" || statusState === "processing";
 	const [dropdownOpen, setDropdownOpen] = useState(false);
 	const [exporting, setExporting] = useState<string | null>(null);
 	const [titleTooltipOpen, setTitleTooltipOpen] = useState(false);
@@ -261,38 +261,38 @@ export const DocumentNode = React.memo(function DocumentNode({
 								className="w-40"
 								onClick={(e) => e.stopPropagation()}
 							>
-								<DropdownMenuItem onClick={() => onPreview(doc)} disabled={isProcessing}>
-									<Eye className="mr-2 h-4 w-4" />
-									Open
+							<DropdownMenuItem onClick={() => onPreview(doc)} disabled={isUnavailable}>
+								<Eye className="mr-2 h-4 w-4" />
+								Open
+							</DropdownMenuItem>
+							{isEditable && (
+								<DropdownMenuItem onClick={() => onEdit(doc)}>
+									<PenLine className="mr-2 h-4 w-4" />
+									Edit
 								</DropdownMenuItem>
-								{isEditable && (
-									<DropdownMenuItem onClick={() => onEdit(doc)}>
-										<PenLine className="mr-2 h-4 w-4" />
-										Edit
-									</DropdownMenuItem>
-								)}
-								<DropdownMenuItem onClick={() => onMove(doc)}>
-									<Move className="mr-2 h-4 w-4" />
-									Move to...
+							)}
+							<DropdownMenuItem onClick={() => onMove(doc)}>
+								<Move className="mr-2 h-4 w-4" />
+								Move to...
+							</DropdownMenuItem>
+							{onExport && (
+								<DropdownMenuSub>
+									<DropdownMenuSubTrigger disabled={isUnavailable}>
+										<Download className="mr-2 h-4 w-4" />
+										Export
+									</DropdownMenuSubTrigger>
+									<DropdownMenuSubContent className="min-w-[180px]">
+										<ExportDropdownItems onExport={handleExport} exporting={exporting} />
+									</DropdownMenuSubContent>
+								</DropdownMenuSub>
+							)}
+							{onVersionHistory && isVersionableType(doc.document_type) && (
+								<DropdownMenuItem disabled={isUnavailable} onClick={() => onVersionHistory(doc)}>
+									<History className="mr-2 h-4 w-4" />
+									Versions
 								</DropdownMenuItem>
-								{onExport && (
-									<DropdownMenuSub>
-										<DropdownMenuSubTrigger disabled={isProcessing}>
-											<Download className="mr-2 h-4 w-4" />
-											Export
-										</DropdownMenuSubTrigger>
-										<DropdownMenuSubContent className="min-w-[180px]">
-											<ExportDropdownItems onExport={handleExport} exporting={exporting} />
-										</DropdownMenuSubContent>
-									</DropdownMenuSub>
-								)}
-								{onVersionHistory && isVersionableType(doc.document_type) && (
-									<DropdownMenuItem disabled={isProcessing} onClick={() => onVersionHistory(doc)}>
-										<History className="mr-2 h-4 w-4" />
-										Versions
-									</DropdownMenuItem>
-								)}
-								<DropdownMenuItem disabled={isProcessing} onClick={() => onDelete(doc)}>
+							)}
+							<DropdownMenuItem disabled={isProcessing} onClick={() => onDelete(doc)}>
 									<Trash2 className="mr-2 h-4 w-4" />
 									Delete
 								</DropdownMenuItem>
@@ -304,38 +304,38 @@ export const DocumentNode = React.memo(function DocumentNode({
 
 			{contextMenuOpen && (
 				<ContextMenuContent className="w-40" onClick={(e) => e.stopPropagation()}>
-					<ContextMenuItem onClick={() => onPreview(doc)} disabled={isProcessing}>
-						<Eye className="mr-2 h-4 w-4" />
-						Open
+				<ContextMenuItem onClick={() => onPreview(doc)} disabled={isUnavailable}>
+					<Eye className="mr-2 h-4 w-4" />
+					Open
+				</ContextMenuItem>
+				{isEditable && (
+					<ContextMenuItem onClick={() => onEdit(doc)}>
+						<PenLine className="mr-2 h-4 w-4" />
+						Edit
 					</ContextMenuItem>
-					{isEditable && (
-						<ContextMenuItem onClick={() => onEdit(doc)}>
-							<PenLine className="mr-2 h-4 w-4" />
-							Edit
-						</ContextMenuItem>
-					)}
-					<ContextMenuItem onClick={() => onMove(doc)}>
-						<Move className="mr-2 h-4 w-4" />
-						Move to...
+				)}
+				<ContextMenuItem onClick={() => onMove(doc)}>
+					<Move className="mr-2 h-4 w-4" />
+					Move to...
+				</ContextMenuItem>
+				{onExport && (
+					<ContextMenuSub>
+						<ContextMenuSubTrigger disabled={isUnavailable}>
+							<Download className="mr-2 h-4 w-4" />
+							Export
+						</ContextMenuSubTrigger>
+						<ContextMenuSubContent className="min-w-[180px]">
+							<ExportContextItems onExport={handleExport} exporting={exporting} />
+						</ContextMenuSubContent>
+					</ContextMenuSub>
+				)}
+				{onVersionHistory && isVersionableType(doc.document_type) && (
+					<ContextMenuItem disabled={isUnavailable} onClick={() => onVersionHistory(doc)}>
+						<History className="mr-2 h-4 w-4" />
+						Versions
 					</ContextMenuItem>
-					{onExport && (
-						<ContextMenuSub>
-							<ContextMenuSubTrigger disabled={isProcessing}>
-								<Download className="mr-2 h-4 w-4" />
-								Export
-							</ContextMenuSubTrigger>
-							<ContextMenuSubContent className="min-w-[180px]">
-								<ExportContextItems onExport={handleExport} exporting={exporting} />
-							</ContextMenuSubContent>
-						</ContextMenuSub>
-					)}
-					{onVersionHistory && isVersionableType(doc.document_type) && (
-						<ContextMenuItem disabled={isProcessing} onClick={() => onVersionHistory(doc)}>
-							<History className="mr-2 h-4 w-4" />
-							Versions
-						</ContextMenuItem>
-					)}
-					<ContextMenuItem disabled={isProcessing} onClick={() => onDelete(doc)}>
+				)}
+				<ContextMenuItem disabled={isProcessing} onClick={() => onDelete(doc)}>
 						<Trash2 className="mr-2 h-4 w-4" />
 						Delete
 					</ContextMenuItem>
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 95bd21e3b..d69f48606 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -627,9 +627,10 @@ export function DocumentsSidebar({
 			function collectSubtreeDocs(parentId: number): DocumentNodeDoc[] {
 				const directDocs = (treeDocuments ?? []).filter(
 					(d) =>
-						d.folderId === parentId &&
-						d.status?.state !== "pending" &&
-						d.status?.state !== "processing"
+					d.folderId === parentId &&
+					d.status?.state !== "pending" &&
+					d.status?.state !== "processing" &&
+					d.status?.state !== "failed"
 				);
 				const childFolders = foldersByParent[String(parentId)] ?? [];
 				const descendantDocs = childFolders.flatMap((cf) => collectSubtreeDocs(cf.id));

From ae3d254a2cd0c456c17344b258bde4c47e437265 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 00:10:57 +0530
Subject: [PATCH 22/28] refactor: enhance inline mention editor and prompt
 picker UI with improved trigger handling and loading states

---
 .../assistant-ui/inline-mention-editor.tsx    |  78 +++++------
 .../new-chat/document-mention-picker.tsx      |  12 +-
 .../components/new-chat/prompt-picker.tsx     | 121 ++++++++++++------
 3 files changed, 117 insertions(+), 94 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/inline-mention-editor.tsx b/surfsense_web/components/assistant-ui/inline-mention-editor.tsx
index 2d55f4d20..f5de0be7d 100644
--- a/surfsense_web/components/assistant-ui/inline-mention-editor.tsx
+++ b/surfsense_web/components/assistant-ui/inline-mention-editor.tsx
@@ -499,10 +499,14 @@ export const InlineMentionEditor = forwardRef<InlineMentionEditorRef, InlineMent
 			const empty = text.length === 0 && mentionedDocs.size === 0;
 			setIsEmpty(empty);
 
-			// Check for @ mentions
+			// Unified trigger scan: find the leftmost @ or / in the current word.
+			// Whichever trigger was typed first owns the token — the other character
+			// is treated as part of the query, not as a separate trigger.
 			const selection = window.getSelection();
 			let shouldTriggerMention = false;
 			let mentionQuery = "";
+			let shouldTriggerAction = false;
+			let actionQuery = "";
 
 			if (selection && selection.rangeCount > 0) {
 				const range = selection.getRangeAt(0);
@@ -512,63 +516,41 @@ export const InlineMentionEditor = forwardRef<InlineMentionEditorRef, InlineMent
 					const textContent = textNode.textContent || "";
 					const cursorPos = range.startOffset;
 
-					// Look for @ before cursor
-					let atIndex = -1;
+					let wordStart = 0;
 					for (let i = cursorPos - 1; i >= 0; i--) {
-						if (textContent[i] === "@") {
-							atIndex = i;
-							break;
-						}
-						// Stop if we hit a space (@ must be at word boundary)
 						if (textContent[i] === " " || textContent[i] === "\n") {
+							wordStart = i + 1;
 							break;
 						}
 					}
 
-					if (atIndex !== -1) {
-						const query = textContent.slice(atIndex + 1, cursorPos);
-						// Only trigger if query doesn't start with space
+					let triggerChar: "@" | "/" | null = null;
+					let triggerIndex = -1;
+					for (let i = wordStart; i < cursorPos; i++) {
+						if (textContent[i] === "@" || textContent[i] === "/") {
+							triggerChar = textContent[i] as "@" | "/";
+							triggerIndex = i;
+							break;
+						}
+					}
+
+					if (triggerChar === "@" && triggerIndex !== -1) {
+						const query = textContent.slice(triggerIndex + 1, cursorPos);
 						if (!query.startsWith(" ")) {
 							shouldTriggerMention = true;
 							mentionQuery = query;
 						}
-					}
-				}
-			}
-
-			// Check for / actions (same pattern as @)
-			let shouldTriggerAction = false;
-			let actionQuery = "";
-
-			if (!shouldTriggerMention && selection && selection.rangeCount > 0) {
-				const range = selection.getRangeAt(0);
-				const textNode = range.startContainer;
-
-				if (textNode.nodeType === Node.TEXT_NODE) {
-					const textContent = textNode.textContent || "";
-					const cursorPos = range.startOffset;
-
-					let slashIndex = -1;
-					for (let i = cursorPos - 1; i >= 0; i--) {
-						if (textContent[i] === "/") {
-							slashIndex = i;
-							break;
-						}
-						if (textContent[i] === " " || textContent[i] === "\n") {
-							break;
-						}
-					}
-
-					if (
-						slashIndex !== -1 &&
-						(slashIndex === 0 ||
-							textContent[slashIndex - 1] === " " ||
-							textContent[slashIndex - 1] === "\n")
-					) {
-						const query = textContent.slice(slashIndex + 1, cursorPos);
-						if (!query.startsWith(" ")) {
-							shouldTriggerAction = true;
-							actionQuery = query;
+					} else if (triggerChar === "/" && triggerIndex !== -1) {
+						if (
+							triggerIndex === 0 ||
+							textContent[triggerIndex - 1] === " " ||
+							textContent[triggerIndex - 1] === "\n"
+						) {
+							const query = textContent.slice(triggerIndex + 1, cursorPos);
+							if (!query.startsWith(" ")) {
+								shouldTriggerAction = true;
+								actionQuery = query;
+							}
 						}
 					}
 				}
diff --git a/surfsense_web/components/new-chat/document-mention-picker.tsx b/surfsense_web/components/new-chat/document-mention-picker.tsx
index 9c6521f31..a087463ba 100644
--- a/surfsense_web/components/new-chat/document-mention-picker.tsx
+++ b/surfsense_web/components/new-chat/document-mention-picker.tsx
@@ -394,12 +394,6 @@ export const DocumentMentionPicker = forwardRef<
 		[selectableDocuments, highlightedIndex, handleSelectDocument, onDone]
 	);
 
-	// Hide popup when there are no documents to display (regardless of fetch state)
-	// Search continues in background; popup reappears when results arrive
-	if (!actualLoading && actualDocuments.length === 0) {
-		return null;
-	}
-
 	return (
 		<div
 			className="fixed shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none"
@@ -547,7 +541,11 @@ export const DocumentMentionPicker = forwardRef<
 							</div>
 						)}
 					</div>
-				) : null}
+				) : (
+					<div className="py-1 px-2">
+						<p className="px-3 py-2 text-xs text-muted-foreground">No matching documents</p>
+					</div>
+				)}
 			</div>
 		</div>
 	);
diff --git a/surfsense_web/components/new-chat/prompt-picker.tsx b/surfsense_web/components/new-chat/prompt-picker.tsx
index 3e6457b8c..d3166cad1 100644
--- a/surfsense_web/components/new-chat/prompt-picker.tsx
+++ b/surfsense_web/components/new-chat/prompt-picker.tsx
@@ -15,7 +15,7 @@ import {
 
 import { promptsAtom } from "@/atoms/prompts/prompts-query.atoms";
 import { userSettingsDialogAtom } from "@/atoms/settings/settings-dialog.atoms";
-import { Spinner } from "@/components/ui/spinner";
+import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
 
 export interface PromptPickerRef {
@@ -60,13 +60,21 @@ export const PromptPicker = forwardRef<PromptPickerRef, PromptPickerProps>(funct
 		}
 	}
 
+	const createPromptIndex = filtered.length;
+	const totalItems = filtered.length + 1;
+
 	const handleSelect = useCallback(
 		(index: number) => {
+			if (index === createPromptIndex) {
+				onDone();
+				setUserSettingsDialog({ open: true, initialTab: "prompts" });
+				return;
+			}
 			const action = filtered[index];
 			if (!action) return;
 			onSelect({ name: action.name, prompt: action.prompt, mode: action.mode });
 		},
-		[filtered, onSelect]
+		[filtered, onSelect, createPromptIndex, onDone, setUserSettingsDialog]
 	);
 
 	useEffect(() => {
@@ -93,69 +101,104 @@ export const PromptPicker = forwardRef<PromptPickerRef, PromptPickerProps>(funct
 		() => ({
 			selectHighlighted: () => handleSelect(highlightedIndex),
 			moveUp: () => {
-				if (filtered.length === 0) return;
 				shouldScrollRef.current = true;
-				setHighlightedIndex((prev) => (prev > 0 ? prev - 1 : filtered.length - 1));
+				setHighlightedIndex((prev) => (prev > 0 ? prev - 1 : totalItems - 1));
 			},
 			moveDown: () => {
-				if (filtered.length === 0) return;
 				shouldScrollRef.current = true;
-				setHighlightedIndex((prev) => (prev < filtered.length - 1 ? prev + 1 : 0));
+				setHighlightedIndex((prev) => (prev < totalItems - 1 ? prev + 1 : 0));
 			},
 		}),
-		[filtered.length, highlightedIndex, handleSelect]
+		[totalItems, highlightedIndex, handleSelect]
 	);
 
 	return (
 		<div
-			className="w-64 rounded-lg border bg-popover shadow-lg overflow-hidden"
-			style={containerStyle}
+			className="fixed shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none"
+			style={{
+				zIndex: 9999,
+				...containerStyle,
+			}}
 		>
-			<div ref={scrollContainerRef} className="max-h-48 overflow-y-auto py-1">
+			<div ref={scrollContainerRef} className="max-h-[180px] sm:max-h-[280px] overflow-y-auto">
 				{isLoading ? (
-					<div className="flex items-center justify-center py-3">
-						<Spinner className="size-4" />
+					<div className="py-1 px-2">
+						<div className="px-3 py-2">
+							<Skeleton className="h-[16px] w-24" />
+						</div>
+						{["a", "b", "c", "d", "e"].map((id, i) => (
+							<div
+								key={id}
+								className={cn(
+									"w-full flex items-center gap-2 px-3 py-2 text-left rounded-md",
+									i >= 3 && "hidden sm:flex"
+								)}
+							>
+								<span className="shrink-0">
+									<Skeleton className="h-4 w-4" />
+								</span>
+								<span className="flex-1 text-sm">
+									<Skeleton className="h-[20px]" style={{ width: `${60 + ((i * 7) % 30)}%` }} />
+								</span>
+							</div>
+						))}
 					</div>
 				) : isError ? (
-					<p className="px-3 py-2 text-xs text-destructive">Failed to load prompts</p>
+					<div className="py-1 px-2">
+						<p className="px-3 py-2 text-xs text-destructive">Failed to load prompts</p>
+					</div>
 				) : filtered.length === 0 ? (
-					<p className="px-3 py-2 text-xs text-muted-foreground">No matching prompts</p>
+					<div className="py-1 px-2">
+						<p className="px-3 py-2 text-xs text-muted-foreground">No matching prompts</p>
+					</div>
 				) : (
-					filtered.map((action, index) => (
+					<div className="py-1 px-2">
+						<div className="px-3 py-2 text-xs font-bold text-muted-foreground/55">
+							Saved Prompts
+						</div>
+						{filtered.map((action, index) => (
+							<button
+								key={action.id}
+								ref={(el) => {
+									if (el) itemRefs.current.set(index, el);
+									else itemRefs.current.delete(index);
+								}}
+								type="button"
+								onClick={() => handleSelect(index)}
+								onMouseEnter={() => setHighlightedIndex(index)}
+								className={cn(
+									"w-full flex items-center gap-2 px-3 py-2 text-left text-sm transition-colors rounded-md cursor-pointer",
+									index === highlightedIndex && "bg-accent"
+								)}
+							>
+								<span className="shrink-0 text-muted-foreground">
+									<Zap className="size-4" />
+								</span>
+								<span className="flex-1 text-sm truncate">{action.name}</span>
+							</button>
+						))}
+
+						<div className="mx-2 my-1 border-t border-border dark:border-white/5" />
 						<button
-							key={action.id}
 							ref={(el) => {
-								if (el) itemRefs.current.set(index, el);
-								else itemRefs.current.delete(index);
+								if (el) itemRefs.current.set(createPromptIndex, el);
+								else itemRefs.current.delete(createPromptIndex);
 							}}
 							type="button"
-							onClick={() => handleSelect(index)}
-							onMouseEnter={() => setHighlightedIndex(index)}
+							onClick={() => handleSelect(createPromptIndex)}
+							onMouseEnter={() => setHighlightedIndex(createPromptIndex)}
 							className={cn(
-								"flex w-full items-center gap-2 px-3 py-1.5 text-sm cursor-pointer",
-								index === highlightedIndex ? "bg-accent" : "hover:bg-accent/50"
+								"w-full flex items-center gap-2 px-3 py-2 text-left text-sm transition-colors rounded-md cursor-pointer text-muted-foreground",
+								highlightedIndex === createPromptIndex ? "bg-accent text-foreground" : "hover:text-foreground hover:bg-accent/50"
 							)}
 						>
-							<span className="text-muted-foreground">
-								<Zap className="size-3.5" />
+							<span className="shrink-0">
+								<Plus className="size-4" />
 							</span>
-							<span className="truncate">{action.name}</span>
+							<span>Create prompt</span>
 						</button>
-					))
+					</div>
 				)}
-
-				<div className="my-1 h-px bg-border mx-2" />
-				<button
-					type="button"
-					onClick={() => {
-						onDone();
-						setUserSettingsDialog({ open: true, initialTab: "prompts" });
-					}}
-					className="flex w-full items-center gap-2 px-3 py-1.5 text-sm text-muted-foreground hover:text-foreground hover:bg-accent/50 cursor-pointer"
-				>
-					<Plus className="size-3.5" />
-					<span>Create prompt</span>
-				</button>
 			</div>
 		</div>
 	);

From f22d7434ce818c8dc32a2d07a8ec65617e4194fc Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 01:10:35 +0530
Subject: [PATCH 23/28] refactor: enhance layout and styling in settings
 components for improved UI consistency

---
 .../settings/general-settings-manager.tsx     | 32 ++++----
 .../settings/image-model-manager.tsx          | 71 ++++++++--------
 .../settings/model-config-manager.tsx         | 82 +++++++++----------
 .../settings/vision-model-manager.tsx         | 70 ++++++++--------
 4 files changed, 123 insertions(+), 132 deletions(-)

diff --git a/surfsense_web/components/settings/general-settings-manager.tsx b/surfsense_web/components/settings/general-settings-manager.tsx
index 99fa02f0d..15d44906b 100644
--- a/surfsense_web/components/settings/general-settings-manager.tsx
+++ b/surfsense_web/components/settings/general-settings-manager.tsx
@@ -189,26 +189,28 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 				</div>
 			</form>
 
-			<div className="border-t pt-6 space-y-2">
+		<div className="border-t pt-6 flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+			<div className="space-y-1">
 				<Label>Export knowledge base</Label>
 				<p className="text-xs text-muted-foreground">
 					Download all documents in this search space as a ZIP of markdown files.
 				</p>
-				<Button
-					type="button"
-					variant="secondary"
-					size="sm"
-					disabled={isExporting}
-					onClick={handleExportKB}
-					className="relative"
-				>
-					<span className={isExporting ? "opacity-0" : ""}>
-						<FolderArchive className="h-3 w-3 opacity-60" />
-					</span>
-					<span className={isExporting ? "opacity-0" : ""}>Export</span>
-					{isExporting && <Spinner size="sm" className="absolute" />}
-				</Button>
 			</div>
+			<Button
+				type="button"
+				variant="secondary"
+				size="sm"
+				disabled={isExporting}
+				onClick={handleExportKB}
+				className="relative w-fit shrink-0"
+			>
+				<span className={isExporting ? "opacity-0" : ""}>
+					<FolderArchive className="h-3 w-3 opacity-60" />
+				</span>
+				<span className={isExporting ? "opacity-0" : ""}>Export</span>
+				{isExporting && <Spinner size="sm" className="absolute" />}
+			</Button>
+		</div>
 		</div>
 	);
 }
diff --git a/surfsense_web/components/settings/image-model-manager.tsx b/surfsense_web/components/settings/image-model-manager.tsx
index 831519aa2..1b92306d4 100644
--- a/surfsense_web/components/settings/image-model-manager.tsx
+++ b/surfsense_web/components/settings/image-model-manager.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { AlertCircle, Dot, Edit3, Info, RefreshCw, Trash2, Wand2 } from "lucide-react";
+import { AlertCircle, Dot, Edit3, Info, RefreshCw, Trash2 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { deleteImageGenConfigMutationAtom } from "@/atoms/image-gen-config/image-gen-config-mutation.atoms";
 import {
@@ -209,20 +209,20 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 							{["skeleton-a", "skeleton-b", "skeleton-c"].map((key) => (
 								<Card key={key} className="border-border/60">
 									<CardContent className="p-4 flex flex-col gap-3">
-										<div className="flex items-start justify-between gap-2">
+										<div className="flex items-center gap-2.5">
+											<Skeleton className="size-4 rounded-full shrink-0" />
 											<div className="space-y-1.5 flex-1 min-w-0">
 												<Skeleton className="h-4 w-28 md:w-32" />
 												<Skeleton className="h-3 w-40 md:w-48" />
 											</div>
 										</div>
-										<div className="flex items-center gap-2">
-											<Skeleton className="h-5 w-16 rounded-full" />
-											<Skeleton className="h-5 w-24 rounded-md" />
-										</div>
-										<div className="flex items-center gap-2 pt-2 border-t border-border/40">
-											<Skeleton className="h-3 w-20" />
-											<Skeleton className="h-4 w-4 rounded-full" />
-											<Skeleton className="h-3 w-16" />
+										<div className="flex items-center pt-2 border-t border-border/40">
+											<Skeleton className="h-3 w-20 flex-1" />
+											<Skeleton className="h-3 w-3 rounded-full shrink-0 mx-1" />
+											<div className="flex-1 flex items-center justify-end gap-1.5">
+												<Skeleton className="h-4 w-4 rounded-full" />
+												<Skeleton className="h-3 w-16" />
+											</div>
 										</div>
 									</CardContent>
 								</Card>
@@ -255,20 +255,25 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 									<div key={config.id}>
 										<Card className="group relative overflow-hidden transition-all duration-200 border-border/60 hover:shadow-md h-full">
 											<CardContent className="p-4 flex flex-col gap-3 h-full">
-												{/* Header: Name + Actions */}
-												<div className="flex items-start justify-between gap-2">
-													<div className="min-w-0 flex-1">
-														<h4 className="text-sm font-semibold tracking-tight truncate">
-															{config.name}
-														</h4>
-														{config.description && (
-															<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
-																{config.description}
-															</p>
-														)}
+												{/* Header: Icon + Name + Actions */}
+												<div className="flex items-center justify-between gap-2">
+													<div className="flex items-center gap-2.5 min-w-0 flex-1">
+														<div className="shrink-0">
+															{getProviderIcon(config.provider, { className: "size-4" })}
+														</div>
+														<div className="min-w-0 flex-1">
+															<h4 className="text-sm font-semibold tracking-tight truncate">
+																{config.name}
+															</h4>
+															{config.description && (
+																<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
+																	{config.description}
+																</p>
+															)}
+														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0.5 shrink-0 sm:opacity-0 sm:group-hover:opacity-100 transition-opacity duration-150">
+														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -277,7 +282,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => openEditDialog(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-foreground"
+																				className="h-6 w-6 text-muted-foreground hover:text-foreground"
 																			>
 																				<Edit3 className="h-3 w-3" />
 																			</Button>
@@ -294,7 +299,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-destructive"
+																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -307,17 +312,9 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 													)}
 												</div>
 
-												{/* Provider + Model */}
-												<div className="flex items-center gap-2 flex-wrap">
-													{getProviderIcon(config.provider, { className: "size-3.5 shrink-0" })}
-													<code className="text-[11px] font-mono text-muted-foreground bg-muted/60 px-2 py-0.5 rounded-md truncate max-w-[160px]">
-														{config.model_name}
-													</code>
-												</div>
-
 												{/* Footer: Date + Creator */}
-												<div className="flex items-center gap-2 pt-2 border-t border-border/40 mt-auto">
-													<span className="text-[11px] text-muted-foreground/60">
+												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
+													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -326,11 +323,11 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 													</span>
 													{member && (
 														<>
-															<Dot className="h-4 w-4 text-muted-foreground/30" />
+															<Dot className="h-4 w-4 text-muted-foreground/30 shrink-0" />
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex items-center gap-1.5 cursor-default">
+																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
@@ -339,7 +336,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 																					{getInitials(member.name)}
 																				</AvatarFallback>
 																			</Avatar>
-																			<span className="text-[11px] text-muted-foreground/60 truncate max-w-[120px]">
+																			<span className="text-[11px] text-muted-foreground/60 truncate">
 																				{member.name}
 																			</span>
 																		</div>
diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/model-config-manager.tsx
index f83251426..cee115ea2 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/model-config-manager.tsx
@@ -10,7 +10,6 @@ import {
 	MessageSquareQuote,
 	RefreshCw,
 	Trash2,
-	Wand2,
 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { membersAtom, myAccessAtom } from "@/atoms/members/members-query.atoms";
@@ -208,28 +207,26 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 					{["skeleton-a", "skeleton-b", "skeleton-c"].map((key) => (
 						<Card key={key} className="border-border/60">
 							<CardContent className="p-4 flex flex-col gap-3">
-								{/* Header */}
-								<div className="flex items-start justify-between gap-2">
+								{/* Header: Icon + Name */}
+								<div className="flex items-start gap-2.5">
+									<Skeleton className="size-4 rounded-full shrink-0 mt-0.5" />
 									<div className="space-y-1.5 flex-1 min-w-0">
 										<Skeleton className="h-4 w-28 md:w-32" />
 										<Skeleton className="h-3 w-40 md:w-48" />
 									</div>
 								</div>
-								{/* Provider + Model */}
-								<div className="flex items-center gap-2">
-									<Skeleton className="h-5 w-16 rounded-full" />
-									<Skeleton className="h-5 w-24 rounded-md" />
-								</div>
 								{/* Feature badges */}
 								<div className="flex items-center gap-1.5">
 									<Skeleton className="h-5 w-20 rounded-full" />
-									<Skeleton className="h-5 w-16 rounded-full" />
 								</div>
 								{/* Footer */}
-								<div className="flex items-center gap-2 pt-2 border-t border-border/40">
-									<Skeleton className="h-3 w-20" />
-									<Skeleton className="h-4 w-4 rounded-full" />
-									<Skeleton className="h-3 w-16" />
+								<div className="flex items-center pt-2 border-t border-border/40">
+									<Skeleton className="h-3 w-20 flex-1" />
+									<Skeleton className="h-3 w-3 rounded-full shrink-0 mx-1" />
+									<div className="flex-1 flex items-center justify-end gap-1.5">
+										<Skeleton className="h-4 w-4 rounded-full" />
+										<Skeleton className="h-3 w-16" />
+									</div>
 								</div>
 							</CardContent>
 						</Card>
@@ -262,20 +259,25 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 									<div key={config.id}>
 										<Card className="group relative overflow-hidden transition-all duration-200 border-border/60 hover:shadow-md h-full">
 											<CardContent className="p-4 flex flex-col gap-3 h-full">
-												{/* Header: Name + Actions */}
-												<div className="flex items-start justify-between gap-2">
-													<div className="min-w-0 flex-1">
-														<h4 className="text-sm font-semibold tracking-tight truncate">
-															{config.name}
-														</h4>
-														{config.description && (
-															<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
-																{config.description}
-															</p>
-														)}
+												{/* Header: Icon + Name + Actions */}
+												<div className="flex items-center justify-between gap-2">
+													<div className="flex items-center gap-2.5 min-w-0 flex-1">
+														<div className="shrink-0">
+															{getProviderIcon(config.provider, { className: "size-4" })}
+														</div>
+														<div className="min-w-0 flex-1">
+															<h4 className="text-sm font-semibold tracking-tight truncate">
+																{config.name}
+															</h4>
+															{config.description && (
+																<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
+																	{config.description}
+																</p>
+															)}
+														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0.5 shrink-0 sm:opacity-0 sm:group-hover:opacity-100 transition-opacity duration-150">
+														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -284,7 +286,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => openEditDialog(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-foreground"
+																				className="h-6 w-6 text-muted-foreground hover:text-foreground"
 																			>
 																				<Edit3 className="h-3 w-3" />
 																			</Button>
@@ -301,7 +303,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-destructive"
+																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -314,20 +316,12 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 													)}
 												</div>
 
-												{/* Provider + Model */}
-												<div className="flex items-center gap-2 flex-wrap">
-													{getProviderIcon(config.provider, { className: "size-3.5 shrink-0" })}
-													<code className="text-[11px] font-mono text-muted-foreground bg-muted/60 px-2 py-0.5 rounded-md truncate max-w-[160px]">
-														{config.model_name}
-													</code>
-												</div>
-
 												{/* Feature badges */}
 												<div className="flex items-center gap-1.5 flex-wrap">
 													{config.citations_enabled && (
 														<Badge
-															variant="outline"
-															className="text-[10px] px-1.5 py-0.5 border-emerald-500/30 text-emerald-700 dark:text-emerald-300 bg-emerald-500/5"
+															variant="secondary"
+															className="text-[10px] px-1.5 py-0.5 border-0 text-muted-foreground bg-muted"
 														>
 															<MessageSquareQuote className="h-2.5 w-2.5 mr-1" />
 															Citations
@@ -336,8 +330,8 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 													{!config.use_default_system_instructions &&
 														config.system_instructions && (
 															<Badge
-																variant="outline"
-																className="text-[10px] px-1.5 py-0.5 border-blue-500/30 text-blue-700 dark:text-blue-300 bg-blue-500/5"
+																variant="secondary"
+																className="text-[10px] px-1.5 py-0.5 border-0 text-muted-foreground bg-muted"
 															>
 																<FileText className="h-2.5 w-2.5 mr-1" />
 																Custom
@@ -346,8 +340,8 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 												</div>
 
 												{/* Footer: Date + Creator */}
-												<div className="flex items-center gap-2 pt-2 border-t border-border/40 mt-auto">
-													<span className="text-[11px] text-muted-foreground/60">
+												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
+													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -356,11 +350,11 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 													</span>
 													{member && (
 														<>
-															<Dot className="h-4 w-4 text-muted-foreground/30" />
+															<Dot className="h-4 w-4 text-muted-foreground/30 shrink-0" />
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex items-center gap-1.5 cursor-default">
+																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
@@ -369,7 +363,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 																					{getInitials(member.name)}
 																				</AvatarFallback>
 																			</Avatar>
-																			<span className="text-[11px] text-muted-foreground/60 truncate max-w-[120px]">
+																			<span className="text-[11px] text-muted-foreground/60 truncate">
 																				{member.name}
 																			</span>
 																		</div>
diff --git a/surfsense_web/components/settings/vision-model-manager.tsx b/surfsense_web/components/settings/vision-model-manager.tsx
index 57ea8c205..ce79ac351 100644
--- a/surfsense_web/components/settings/vision-model-manager.tsx
+++ b/surfsense_web/components/settings/vision-model-manager.tsx
@@ -208,20 +208,20 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 							{["skeleton-a", "skeleton-b", "skeleton-c"].map((key) => (
 								<Card key={key} className="border-border/60">
 									<CardContent className="p-4 flex flex-col gap-3">
-										<div className="flex items-start justify-between gap-2">
+										<div className="flex items-center gap-2.5">
+											<Skeleton className="size-4 rounded-full shrink-0" />
 											<div className="space-y-1.5 flex-1 min-w-0">
 												<Skeleton className="h-4 w-28 md:w-32" />
 												<Skeleton className="h-3 w-40 md:w-48" />
 											</div>
 										</div>
-										<div className="flex items-center gap-2">
-											<Skeleton className="h-5 w-16 rounded-full" />
-											<Skeleton className="h-5 w-24 rounded-md" />
-										</div>
-										<div className="flex items-center gap-2 pt-2 border-t border-border/40">
-											<Skeleton className="h-3 w-20" />
-											<Skeleton className="h-4 w-4 rounded-full" />
-											<Skeleton className="h-3 w-16" />
+										<div className="flex items-center pt-2 border-t border-border/40">
+											<Skeleton className="h-3 w-20 flex-1" />
+											<Skeleton className="h-3 w-3 rounded-full shrink-0 mx-1" />
+											<div className="flex-1 flex items-center justify-end gap-1.5">
+												<Skeleton className="h-4 w-4 rounded-full" />
+												<Skeleton className="h-3 w-16" />
+											</div>
 										</div>
 									</CardContent>
 								</Card>
@@ -253,19 +253,25 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 									<div key={config.id}>
 										<Card className="group relative overflow-hidden transition-all duration-200 border-border/60 hover:shadow-md h-full">
 											<CardContent className="p-4 flex flex-col gap-3 h-full">
-												<div className="flex items-start justify-between gap-2">
-													<div className="min-w-0 flex-1">
-														<h4 className="text-sm font-semibold tracking-tight truncate">
-															{config.name}
-														</h4>
-														{config.description && (
-															<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
-																{config.description}
-															</p>
-														)}
+												{/* Header: Icon + Name + Actions */}
+												<div className="flex items-center justify-between gap-2">
+													<div className="flex items-center gap-2.5 min-w-0 flex-1">
+														<div className="shrink-0">
+															{getProviderIcon(config.provider, { className: "size-4" })}
+														</div>
+														<div className="min-w-0 flex-1">
+															<h4 className="text-sm font-semibold tracking-tight truncate">
+																{config.name}
+															</h4>
+															{config.description && (
+																<p className="text-[11px] text-muted-foreground/70 truncate mt-0.5">
+																	{config.description}
+																</p>
+															)}
+														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0.5 shrink-0 sm:opacity-0 sm:group-hover:opacity-100 transition-opacity duration-150">
+														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -274,7 +280,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => openEditDialog(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-foreground"
+																				className="h-6 w-6 text-muted-foreground hover:text-foreground"
 																			>
 																				<Edit3 className="h-3 w-3" />
 																			</Button>
@@ -291,7 +297,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-7 w-7 text-muted-foreground hover:text-destructive"
+																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -304,17 +310,9 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 													)}
 												</div>
 
-												<div className="flex items-center gap-2 flex-wrap">
-													{getProviderIcon(config.provider, {
-														className: "size-3.5 shrink-0",
-													})}
-													<code className="text-[11px] font-mono text-muted-foreground bg-muted/60 px-2 py-0.5 rounded-md truncate max-w-[160px]">
-														{config.model_name}
-													</code>
-												</div>
-
-												<div className="flex items-center gap-2 pt-2 border-t border-border/40 mt-auto">
-													<span className="text-[11px] text-muted-foreground/60">
+												{/* Footer: Date + Creator */}
+												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
+													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -323,11 +321,11 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 													</span>
 													{member && (
 														<>
-															<Dot className="h-4 w-4 text-muted-foreground/30" />
+															<Dot className="h-4 w-4 text-muted-foreground/30 shrink-0" />
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex items-center gap-1.5 cursor-default">
+																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
@@ -336,7 +334,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 																					{getInitials(member.name)}
 																				</AvatarFallback>
 																			</Avatar>
-																			<span className="text-[11px] text-muted-foreground/60 truncate max-w-[120px]">
+																			<span className="text-[11px] text-muted-foreground/60 truncate">
 																				{member.name}
 																			</span>
 																		</div>

From 2b40592f0bb70b833592212bcecb48cc486964eb Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 01:30:30 +0530
Subject: [PATCH 24/28] feat: add Agent Model Manager component for managing
 LLM configurations and enhance UI in related components

---
 ...-config-manager.tsx => agent-model-manager.tsx} | 14 +++++++-------
 .../components/settings/image-model-manager.tsx    | 10 +++++-----
 .../settings/search-space-settings-dialog.tsx      | 10 +++++-----
 .../components/settings/vision-model-manager.tsx   |  8 ++++----
 surfsense_web/messages/en.json                     |  4 ++--
 surfsense_web/messages/es.json                     |  4 ++--
 surfsense_web/messages/hi.json                     |  4 ++--
 surfsense_web/messages/pt.json                     |  4 ++--
 surfsense_web/messages/zh.json                     |  4 ++--
 9 files changed, 31 insertions(+), 31 deletions(-)
 rename surfsense_web/components/settings/{model-config-manager.tsx => agent-model-manager.tsx} (96%)

diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/agent-model-manager.tsx
similarity index 96%
rename from surfsense_web/components/settings/model-config-manager.tsx
rename to surfsense_web/components/settings/agent-model-manager.tsx
index cee115ea2..f7a2fb824 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/agent-model-manager.tsx
@@ -42,7 +42,7 @@ import { useMediaQuery } from "@/hooks/use-media-query";
 import { getProviderIcon } from "@/lib/provider-icons";
 import { cn } from "@/lib/utils";
 
-interface ModelConfigManagerProps {
+interface AgentModelManagerProps {
 	searchSpaceId: number;
 }
 
@@ -54,7 +54,7 @@ function getInitials(name: string): string {
 	return name.slice(0, 2).toUpperCase();
 }
 
-export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
+export function AgentModelManager({ searchSpaceId }: AgentModelManagerProps) {
 	const isDesktop = useMediaQuery("(min-width: 768px)");
 	// Mutations
 	const { mutateAsync: deleteConfig, isPending: isDeleting } = useAtomValue(
@@ -277,7 +277,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
+														<div className="flex items-center gap-1 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -286,7 +286,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => openEditDialog(config)}
-																				className="h-6 w-6 text-muted-foreground hover:text-foreground"
+																				className="h-7 w-7 rounded-lg text-muted-foreground hover:text-foreground"
 																			>
 																				<Edit3 className="h-3 w-3" />
 																			</Button>
@@ -303,7 +303,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
+																				className="h-7 w-7 rounded-lg text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -341,7 +341,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 
 												{/* Footer: Date + Creator */}
 												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
-													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
+													<span className="shrink-0 text-[11px] text-muted-foreground/60 whitespace-nowrap">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -354,7 +354,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
+																		<div className="min-w-0 flex items-center gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
diff --git a/surfsense_web/components/settings/image-model-manager.tsx b/surfsense_web/components/settings/image-model-manager.tsx
index 1b92306d4..fb28e5b1c 100644
--- a/surfsense_web/components/settings/image-model-manager.tsx
+++ b/surfsense_web/components/settings/image-model-manager.tsx
@@ -273,7 +273,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
+														<div className="flex items-center gap-1 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -282,7 +282,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => openEditDialog(config)}
-																				className="h-6 w-6 text-muted-foreground hover:text-foreground"
+																				className="h-7 w-7 rounded-lg text-muted-foreground hover:text-foreground"
 																			>
 																				<Edit3 className="h-3 w-3" />
 																			</Button>
@@ -299,7 +299,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
+																				className="h-7 w-7 rounded-lg text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -314,7 +314,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 
 												{/* Footer: Date + Creator */}
 												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
-													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
+													<span className="shrink-0 text-[11px] text-muted-foreground/60 whitespace-nowrap">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -327,7 +327,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
+																		<div className="min-w-0 flex items-center gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
diff --git a/surfsense_web/components/settings/search-space-settings-dialog.tsx b/surfsense_web/components/settings/search-space-settings-dialog.tsx
index 4469addf4..e021e1e41 100644
--- a/surfsense_web/components/settings/search-space-settings-dialog.tsx
+++ b/surfsense_web/components/settings/search-space-settings-dialog.tsx
@@ -25,10 +25,10 @@ const GeneralSettingsManager = dynamic(
 		})),
 	{ ssr: false }
 );
-const ModelConfigManager = dynamic(
+const AgentModelManager = dynamic(
 	() =>
-		import("@/components/settings/model-config-manager").then((m) => ({
-			default: m.ModelConfigManager,
+		import("@/components/settings/agent-model-manager").then((m) => ({
+			default: m.AgentModelManager,
 		})),
 	{ ssr: false }
 );
@@ -88,7 +88,7 @@ export function SearchSpaceSettingsDialog({ searchSpaceId }: SearchSpaceSettings
 	const navItems = [
 		{ value: "general", label: t("nav_general"), icon: <CircleUser className="h-4 w-4" /> },
 		{ value: "roles", label: t("nav_role_assignments"), icon: <ListChecks className="h-4 w-4" /> },
-		{ value: "models", label: t("nav_agent_configs"), icon: <Bot className="h-4 w-4" /> },
+		{ value: "models", label: t("nav_agent_models"), icon: <Bot className="h-4 w-4" /> },
 		{
 			value: "image-models",
 			label: t("nav_image_models"),
@@ -115,7 +115,7 @@ export function SearchSpaceSettingsDialog({ searchSpaceId }: SearchSpaceSettings
 
 	const content: Record<string, React.ReactNode> = {
 		general: <GeneralSettingsManager searchSpaceId={searchSpaceId} />,
-		models: <ModelConfigManager searchSpaceId={searchSpaceId} />,
+		models: <AgentModelManager searchSpaceId={searchSpaceId} />,
 		roles: <LLMRoleManager searchSpaceId={searchSpaceId} />,
 		"image-models": <ImageModelManager searchSpaceId={searchSpaceId} />,
 		"vision-models": <VisionModelManager searchSpaceId={searchSpaceId} />,
diff --git a/surfsense_web/components/settings/vision-model-manager.tsx b/surfsense_web/components/settings/vision-model-manager.tsx
index ce79ac351..81528c86a 100644
--- a/surfsense_web/components/settings/vision-model-manager.tsx
+++ b/surfsense_web/components/settings/vision-model-manager.tsx
@@ -271,7 +271,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 														</div>
 													</div>
 													{(canUpdate || canDelete) && (
-														<div className="flex items-center gap-0 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
+														<div className="flex items-center gap-1 shrink-0 sm:w-0 sm:overflow-hidden sm:group-hover:w-auto sm:opacity-0 sm:group-hover:opacity-100 transition-all duration-150">
 															{canUpdate && (
 																<TooltipProvider>
 																	<Tooltip open={isDesktop ? undefined : false}>
@@ -297,7 +297,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 																				variant="ghost"
 																				size="icon"
 																				onClick={() => setConfigToDelete(config)}
-																				className="h-6 w-6 text-muted-foreground hover:text-destructive"
+																				className="h-7 w-7 rounded-lg text-muted-foreground hover:text-destructive"
 																			>
 																				<Trash2 className="h-3 w-3" />
 																			</Button>
@@ -312,7 +312,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 
 												{/* Footer: Date + Creator */}
 												<div className="flex items-center pt-2 border-t border-border/40 mt-auto">
-													<span className="flex-1 min-w-0 text-[11px] text-muted-foreground/60 truncate">
+													<span className="shrink-0 text-[11px] text-muted-foreground/60 whitespace-nowrap">
 														{new Date(config.created_at).toLocaleDateString(undefined, {
 															year: "numeric",
 															month: "short",
@@ -325,7 +325,7 @@ export function VisionModelManager({ searchSpaceId }: VisionModelManagerProps) {
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
-																		<div className="flex-1 min-w-0 flex items-center justify-end gap-1.5 cursor-default">
+																		<div className="min-w-0 flex items-center gap-1.5 cursor-default">
 																			<Avatar className="size-4.5 shrink-0">
 																				{member.avatarUrl && (
 																					<AvatarImage src={member.avatarUrl} alt={member.name} />
diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index ed38b8da3..701cb086d 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -737,8 +737,8 @@
 		"back_to_app": "Back to app",
 		"nav_general": "General",
 		"nav_general_desc": "Name, description & basic info",
-		"nav_agent_configs": "Agent Configs",
-		"nav_agent_configs_desc": "Models with prompts & citations",
+		"nav_agent_models": "Agent Models",
+		"nav_agent_models_desc": "Models with prompts & citations",
 		"nav_role_assignments": "Role Assignments",
 		"nav_role_assignments_desc": "Assign configs to agent roles",
 		"nav_image_models": "Image Models",
diff --git a/surfsense_web/messages/es.json b/surfsense_web/messages/es.json
index 920642b9b..9c872e701 100644
--- a/surfsense_web/messages/es.json
+++ b/surfsense_web/messages/es.json
@@ -737,8 +737,8 @@
 		"back_to_app": "Volver a la app",
 		"nav_general": "General",
 		"nav_general_desc": "Nombre, descripción e información básica",
-		"nav_agent_configs": "Configuraciones de agente",
-		"nav_agent_configs_desc": "Modelos LLM con prompts y citas",
+		"nav_agent_models": "Modelos de agente",
+		"nav_agent_models_desc": "Modelos LLM con prompts y citas",
 		"nav_role_assignments": "Asignaciones de roles",
 		"nav_role_assignments_desc": "Asignar configuraciones a roles de agente",
 		"nav_image_models": "Modelos de imagen",
diff --git a/surfsense_web/messages/hi.json b/surfsense_web/messages/hi.json
index 1e1069b0b..3b6975bf5 100644
--- a/surfsense_web/messages/hi.json
+++ b/surfsense_web/messages/hi.json
@@ -737,8 +737,8 @@
 		"back_to_app": "ऐप पर वापस जाएं",
 		"nav_general": "सामान्य",
 		"nav_general_desc": "नाम, विवरण और बुनियादी जानकारी",
-		"nav_agent_configs": "एजेंट कॉन्फ़िगरेशन",
-		"nav_agent_configs_desc": "प्रॉम्प्ट और उद्धरण के साथ LLM मॉडल",
+		"nav_agent_models": "एजेंट मॉडल",
+		"nav_agent_models_desc": "प्रॉम्प्ट और उद्धरण के साथ LLM मॉडल",
 		"nav_role_assignments": "भूमिका असाइनमेंट",
 		"nav_role_assignments_desc": "एजेंट भूमिकाओं को कॉन्फ़िगरेशन असाइन करें",
 		"nav_image_models": "इमेज मॉडल",
diff --git a/surfsense_web/messages/pt.json b/surfsense_web/messages/pt.json
index d4f879486..e92dff375 100644
--- a/surfsense_web/messages/pt.json
+++ b/surfsense_web/messages/pt.json
@@ -737,8 +737,8 @@
 		"back_to_app": "Voltar ao app",
 		"nav_general": "Geral",
 		"nav_general_desc": "Nome, descrição e informações básicas",
-		"nav_agent_configs": "Configurações do agente",
-		"nav_agent_configs_desc": "Modelos LLM com prompts e citações",
+		"nav_agent_models": "Modelos do agente",
+		"nav_agent_models_desc": "Modelos LLM com prompts e citações",
 		"nav_role_assignments": "Atribuições de funções",
 		"nav_role_assignments_desc": "Atribuir configurações a funções do agente",
 		"nav_image_models": "Modelos de imagem",
diff --git a/surfsense_web/messages/zh.json b/surfsense_web/messages/zh.json
index ac3acc650..c53155edf 100644
--- a/surfsense_web/messages/zh.json
+++ b/surfsense_web/messages/zh.json
@@ -721,8 +721,8 @@
 		"back_to_app": "返回应用",
 		"nav_general": "常规",
 		"nav_general_desc": "名称、描述和基本信息",
-		"nav_agent_configs": "代理配置",
-		"nav_agent_configs_desc": "LLM 模型配置提示词和引用",
+		"nav_agent_models": "代理模型",
+		"nav_agent_models_desc": "LLM 模型配置提示词和引用",
 		"nav_role_assignments": "角色分配",
 		"nav_role_assignments_desc": "为代理角色分配配置",
 		"nav_image_models": "图像模型",

From 3d1a504395c1e8b4b58014850d4322508a3531b7 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 01:50:37 +0530
Subject: [PATCH 25/28] refactor: streamline Composer component by removing
 unused state and simplifying popover handling

---
 .../components/assistant-ui/thread.tsx        | 122 ++++++------------
 .../new-chat/document-mention-picker.tsx      |   9 +-
 .../components/new-chat/prompt-picker.tsx     |  11 +-
 3 files changed, 41 insertions(+), 101 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 7fb01401f..c8851acc6 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -28,8 +28,7 @@ import {
 import { AnimatePresence, motion } from "motion/react";
 import Image from "next/image";
 import { useParams } from "next/navigation";
-import { type FC, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { createPortal } from "react-dom";
+import { type FC, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
 	agentToolsAtom,
 	disabledToolsAtom,
@@ -339,10 +338,7 @@ const Composer: FC = () => {
 	const [showPromptPicker, setShowPromptPicker] = useState(false);
 	const [mentionQuery, setMentionQuery] = useState("");
 	const [actionQuery, setActionQuery] = useState("");
-	const [containerPos, setContainerPos] = useState({ bottom: "200px", left: "50%", top: "auto" });
 	const editorRef = useRef<InlineMentionEditorRef>(null);
-	const editorContainerRef = useRef<HTMLDivElement>(null);
-	const composerBoxRef = useRef<HTMLDivElement>(null);
 	const documentPickerRef = useRef<DocumentMentionPickerRef>(null);
 	const promptPickerRef = useRef<PromptPickerRef>(null);
 	const viewportRef = useRef<Element | null>(null);
@@ -363,38 +359,13 @@ const Composer: FC = () => {
 		viewportRef.current = document.querySelector(".aui-thread-viewport");
 	}, []);
 
-	// Compute picker positions using ResizeObserver to avoid layout reads during render
-	useLayoutEffect(() => {
-		if (!editorContainerRef.current) return;
-
-		const updatePosition = () => {
-			if (!editorContainerRef.current) return;
-			const rect = editorContainerRef.current.getBoundingClientRect();
-			const composerRect = composerBoxRef.current?.getBoundingClientRect();
-			setContainerPos({
-				bottom: `${window.innerHeight - rect.top + 8}px`,
-				left: `${rect.left}px`,
-				top: composerRect ? `${composerRect.bottom + 8}px` : "auto",
-			});
-		};
-
-		updatePosition();
-		const ro = new ResizeObserver(updatePosition);
-		ro.observe(editorContainerRef.current);
-		if (composerBoxRef.current) {
-			ro.observe(composerBoxRef.current);
-		}
-
-		return () => ro.disconnect();
-	}, []);
-
 	const electronAPI = useElectronAPI();
 	const [clipboardInitialText, setClipboardInitialText] = useState<string | undefined>();
 	const clipboardLoadedRef = useRef(false);
 	useEffect(() => {
 		if (!electronAPI || clipboardLoadedRef.current) return;
 		clipboardLoadedRef.current = true;
-		electronAPI.getQuickAskText().then((text) => {
+		electronAPI.getQuickAskText().then((text: string) => {
 			if (text) {
 				setClipboardInitialText(text);
 			}
@@ -705,28 +676,54 @@ const Composer: FC = () => {
 	);
 
 	return (
-		<ComposerPrimitive.Root
-			className="aui-composer-root relative flex w-full flex-col gap-2"
-			style={showPromptPicker && clipboardInitialText ? { marginBottom: 220 } : undefined}
-		>
+		<ComposerPrimitive.Root className="aui-composer-root relative flex w-full flex-col gap-2">
 			<ChatSessionStatus
 				isAiResponding={isAiResponding}
 				respondingToUserId={respondingToUserId}
 				currentUserId={currentUser?.id ?? null}
 				members={members ?? []}
 			/>
-			<div
-				ref={composerBoxRef}
-				className="aui-composer-attachment-dropzone flex w-full flex-col overflow-hidden rounded-2xl border-input bg-muted pt-2 outline-none transition-shadow"
-			>
+			{showDocumentPopover && (
+				<div className="absolute bottom-full left-0 z-[9999] mb-2">
+					<DocumentMentionPicker
+						ref={documentPickerRef}
+						searchSpaceId={Number(search_space_id)}
+						onSelectionChange={handleDocumentsMention}
+						onDone={() => {
+							setShowDocumentPopover(false);
+							setMentionQuery("");
+						}}
+						initialSelectedDocuments={mentionedDocuments}
+						externalSearch={mentionQuery}
+					/>
+				</div>
+			)}
+			{showPromptPicker && (
+				<div
+					className={cn(
+						"absolute left-0 z-[9999]",
+						clipboardInitialText ? "top-full mt-2" : "bottom-full mb-2"
+					)}
+				>
+					<PromptPicker
+						ref={promptPickerRef}
+						onSelect={clipboardInitialText ? handleQuickAskSelect : handleActionSelect}
+						onDone={() => {
+							setShowPromptPicker(false);
+							setActionQuery("");
+						}}
+						externalSearch={actionQuery}
+					/>
+				</div>
+			)}
+			<div className="aui-composer-attachment-dropzone flex w-full flex-col overflow-hidden rounded-2xl border-input bg-muted pt-2 outline-none transition-shadow">
 				{clipboardInitialText && (
 					<ClipboardChip
 						text={clipboardInitialText}
 						onDismiss={() => setClipboardInitialText(undefined)}
 					/>
 				)}
-				{/* Inline editor with @mention support */}
-				<div ref={editorContainerRef} className="aui-composer-input-wrapper px-4 pt-3 pb-6">
+				<div className="aui-composer-input-wrapper px-4 pt-3 pb-6">
 					<InlineMentionEditor
 						ref={editorRef}
 						placeholder={currentPlaceholder}
@@ -741,49 +738,6 @@ const Composer: FC = () => {
 						className="min-h-[24px]"
 					/>
 				</div>
-				{/* Document picker popover (portal to body for proper z-index stacking) */}
-				{showDocumentPopover &&
-					typeof document !== "undefined" &&
-					createPortal(
-						<DocumentMentionPicker
-							ref={documentPickerRef}
-							searchSpaceId={Number(search_space_id)}
-							onSelectionChange={handleDocumentsMention}
-							onDone={() => {
-								setShowDocumentPopover(false);
-								setMentionQuery("");
-							}}
-							initialSelectedDocuments={mentionedDocuments}
-							externalSearch={mentionQuery}
-							containerStyle={{
-								bottom: containerPos.bottom,
-								left: containerPos.left,
-							}}
-						/>,
-						document.body
-					)}
-				{showPromptPicker &&
-					typeof document !== "undefined" &&
-					createPortal(
-						<PromptPicker
-							ref={promptPickerRef}
-							onSelect={clipboardInitialText ? handleQuickAskSelect : handleActionSelect}
-							onDone={() => {
-								setShowPromptPicker(false);
-								setActionQuery("");
-							}}
-							externalSearch={actionQuery}
-							containerStyle={{
-								position: "fixed",
-								...(clipboardInitialText
-									? { top: containerPos.top }
-									: { bottom: containerPos.bottom }),
-								left: containerPos.left,
-								zIndex: 50,
-							}}
-						/>,
-						document.body
-					)}
 				<ComposerAction isBlockedByOtherUser={isBlockedByOtherUser} />
 				<ConnectorIndicator showTrigger={false} />
 				<ConnectToolsBanner isThreadEmpty={isThreadEmpty} />
diff --git a/surfsense_web/components/new-chat/document-mention-picker.tsx b/surfsense_web/components/new-chat/document-mention-picker.tsx
index a087463ba..f2985278d 100644
--- a/surfsense_web/components/new-chat/document-mention-picker.tsx
+++ b/surfsense_web/components/new-chat/document-mention-picker.tsx
@@ -29,8 +29,6 @@ interface DocumentMentionPickerProps {
 	onDone: () => void;
 	initialSelectedDocuments?: Pick<Document, "id" | "title" | "document_type">[];
 	externalSearch?: string;
-	/** Positioning styles for the container */
-	containerStyle?: React.CSSProperties;
 }
 
 const PAGE_SIZE = 20;
@@ -75,7 +73,6 @@ export const DocumentMentionPicker = forwardRef<
 		onDone,
 		initialSelectedDocuments = [],
 		externalSearch = "",
-		containerStyle,
 	},
 	ref
 ) {
@@ -396,11 +393,7 @@ export const DocumentMentionPicker = forwardRef<
 
 	return (
 		<div
-			className="fixed shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none"
-			style={{
-				zIndex: 9999,
-				...containerStyle,
-			}}
+			className="shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none"
 			onKeyDown={handleKeyDown}
 			role="listbox"
 			tabIndex={-1}
diff --git a/surfsense_web/components/new-chat/prompt-picker.tsx b/surfsense_web/components/new-chat/prompt-picker.tsx
index d3166cad1..b1723f0be 100644
--- a/surfsense_web/components/new-chat/prompt-picker.tsx
+++ b/surfsense_web/components/new-chat/prompt-picker.tsx
@@ -28,11 +28,10 @@ interface PromptPickerProps {
 	onSelect: (action: { name: string; prompt: string; mode: "transform" | "explore" }) => void;
 	onDone: () => void;
 	externalSearch?: string;
-	containerStyle?: React.CSSProperties;
 }
 
 export const PromptPicker = forwardRef<PromptPickerRef, PromptPickerProps>(function PromptPicker(
-	{ onSelect, onDone, externalSearch = "", containerStyle },
+	{ onSelect, onDone, externalSearch = "" },
 	ref
 ) {
 	const setUserSettingsDialog = useSetAtom(userSettingsDialogAtom);
@@ -113,13 +112,7 @@ export const PromptPicker = forwardRef<PromptPickerRef, PromptPickerProps>(funct
 	);
 
 	return (
-		<div
-			className="fixed shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none"
-			style={{
-				zIndex: 9999,
-				...containerStyle,
-			}}
-		>
+		<div className="shadow-2xl rounded-lg border border-border dark:border-white/5 overflow-hidden bg-popover dark:bg-neutral-900 flex flex-col w-[280px] sm:w-[320px] select-none">
 			<div ref={scrollContainerRef} className="max-h-[180px] sm:max-h-[280px] overflow-y-auto">
 				{isLoading ? (
 					<div className="py-1 px-2">

From 43744713f76cf23a10986fc6d44f4908cca0fe5f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 02:38:49 +0530
Subject: [PATCH 26/28] refactor: simplify Composer component logic and improve
 message submission handling

---
 .../components/assistant-ui/thread.tsx        | 45 ++++++-------------
 1 file changed, 13 insertions(+), 32 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index c8851acc6..639ef8a89 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -128,11 +128,9 @@ const ThreadContent: FC = () => {
 					style={{ paddingBottom: "max(1rem, env(safe-area-inset-bottom))" }}
 				>
 					<ThreadScrollToBottom />
-					<AuiIf condition={({ thread }) => !thread.isEmpty}>
-						<div className="fade-in slide-in-from-bottom-4 animate-in duration-500 ease-out fill-mode-both">
-							<Composer />
-						</div>
-					</AuiIf>
+				<AuiIf condition={({ thread }) => !thread.isEmpty}>
+					<Composer />
+				</AuiIf>
 				</ThreadPrimitive.ViewportFooter>
 			</ThreadPrimitive.Viewport>
 		</ThreadPrimitive.Root>
@@ -558,23 +556,15 @@ const Composer: FC = () => {
 
 	// Submit message (blocked during streaming, document picker open, or AI responding to another user)
 	const handleSubmit = useCallback(() => {
-		if (isThreadRunning || isBlockedByOtherUser) {
-			return;
-		}
-		if (!showDocumentPopover && !showPromptPicker) {
-			if (clipboardInitialText) {
-				const userText = editorRef.current?.getText() ?? "";
-				const combined = userText ? `${userText}\n\n${clipboardInitialText}` : clipboardInitialText;
-				aui.composer().setText(combined);
-				setClipboardInitialText(undefined);
-			}
-			aui.composer().send();
-			editorRef.current?.clear();
-			setMentionedDocuments([]);
-			setSidebarDocs([]);
-		}
 		if (isThreadRunning || isBlockedByOtherUser) return;
-		if (showDocumentPopover) return;
+		if (showDocumentPopover || showPromptPicker) return;
+
+		if (clipboardInitialText) {
+			const userText = editorRef.current?.getText() ?? "";
+			const combined = userText ? `${userText}\n\n${clipboardInitialText}` : clipboardInitialText;
+			aui.composer().setText(combined);
+			setClipboardInitialText(undefined);
+		}
 
 		const viewportEl = viewportRef.current;
 		const heightBefore = viewportEl?.scrollHeight ?? 0;
@@ -588,18 +578,14 @@ const Composer: FC = () => {
 		// assistant message so that scrolling-to-bottom actually positions the
 		// user message at the TOP of the viewport. That slack height is
 		// calculated asynchronously (ResizeObserver → style → layout).
-		//
-		// We poll via rAF for ~2 s, re-scrolling whenever scrollHeight changes
-		// (user msg render → assistant placeholder → ViewportSlack min-height →
-		// first streamed content). Backup setTimeout calls cover cases where
-		// the batcher's 50 ms throttle delays the DOM update past the rAF.
+		// Poll via rAF for ~500ms, re-scrolling whenever scrollHeight changes.
 		const scrollToBottom = () =>
 			threadViewportStore.getState().scrollToBottom({ behavior: "instant" });
 
 		let lastHeight = heightBefore;
 		let frames = 0;
 		let cancelled = false;
-		const POLL_FRAMES = 120;
+		const POLL_FRAMES = 30;
 
 		const pollAndScroll = () => {
 			if (cancelled) return;
@@ -619,16 +605,11 @@ const Composer: FC = () => {
 
 		const t1 = setTimeout(scrollToBottom, 100);
 		const t2 = setTimeout(scrollToBottom, 300);
-		const t3 = setTimeout(scrollToBottom, 600);
 
-		// Cleanup if component unmounts during the polling window. The ref is
-		// checked inside pollAndScroll; timeouts are cleared in the return below.
-		// Store cleanup fn so it can be called from a useEffect cleanup if needed.
 		submitCleanupRef.current = () => {
 			cancelled = true;
 			clearTimeout(t1);
 			clearTimeout(t2);
-			clearTimeout(t3);
 		};
 	}, [
 		showDocumentPopover,

From 26695b949eb2844d20c16fd028b7ae612e92506e Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 03:57:37 +0530
Subject: [PATCH 27/28] refactor: enhance ThreadContent layout and improve
 navigation handling in LayoutDataProvider

---
 .../components/assistant-ui/thread.tsx        |  4 ++
 .../layout/providers/LayoutDataProvider.tsx   | 14 +++----
 .../tool-ui/generic-hitl-approval.tsx         | 42 +++++++++----------
 3 files changed, 29 insertions(+), 31 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 639ef8a89..59797fc72 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -123,6 +123,10 @@ const ThreadContent: FC = () => {
 					}}
 				/>
 
+				<AuiIf condition={({ thread }) => !thread.isEmpty}>
+					<div className="grow" />
+				</AuiIf>
+
 				<ThreadPrimitive.ViewportFooter
 					className="aui-thread-viewport-footer sticky bottom-0 z-10 mx-auto flex w-full max-w-(--thread-max-width) flex-col gap-4 overflow-visible rounded-t-3xl bg-main-panel pb-4 md:pb-6"
 					style={{ paddingBottom: "max(1rem, env(safe-area-inset-bottom))" }}
diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index 7e9c33a1a..aecf55a27 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -532,16 +532,14 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 		const isOutOfSync = currentThreadState.id !== null && !params?.chat_id;
 
 		if (isOutOfSync) {
-			// First sync Next.js router by navigating to the current chat's actual URL
-			// This updates the router's internal state to match the browser URL
 			resetCurrentThread();
-			router.replace(`/dashboard/${searchSpaceId}/new-chat/${currentThreadState.id}`);
-			// Allow router to sync, then navigate to fresh new-chat
-			setTimeout(() => {
-				router.push(`/dashboard/${searchSpaceId}/new-chat`);
-			}, 0);
+			// Immediately set the browser URL so the page remounts with a clean /new-chat path
+			window.history.replaceState(null, "", `/dashboard/${searchSpaceId}/new-chat`);
+			// Force-remount the page component to reset all React state synchronously
+			setChatResetKey((k) => k + 1);
+			// Sync Next.js router internals so useParams/usePathname stay correct going forward
+			router.replace(`/dashboard/${searchSpaceId}/new-chat`);
 		} else {
-			// Normal navigation - router is in sync
 			router.push(`/dashboard/${searchSpaceId}/new-chat`);
 		}
 	}, [router, searchSpaceId, currentThreadState.id, params?.chat_id, resetCurrentThread]);
diff --git a/surfsense_web/components/tool-ui/generic-hitl-approval.tsx b/surfsense_web/components/tool-ui/generic-hitl-approval.tsx
index 48d0d3764..2a26b18f7 100644
--- a/surfsense_web/components/tool-ui/generic-hitl-approval.tsx
+++ b/surfsense_web/components/tool-ui/generic-hitl-approval.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-import { CornerDownLeftIcon, ShieldAlertIcon, ShieldCheckIcon } from "lucide-react";
+import { CornerDownLeftIcon, Pen } from "lucide-react";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
 import { Button } from "@/components/ui/button";
@@ -134,17 +134,14 @@ function GenericApprovalCard({
 	return (
 		<div className="my-4 max-w-lg overflow-hidden rounded-2xl border bg-muted/30 transition-[box-shadow] duration-300">
 			{/* Header */}
-			<div className="flex items-start gap-3 px-5 pt-5 pb-4 select-none">
-				<div className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-amber-500/10">
-					<ShieldAlertIcon className="size-4 text-amber-600" />
-				</div>
-				<div className="flex-1 min-w-0">
+			<div className="flex items-start justify-between px-5 pt-5 pb-4 select-none">
+				<div>
 					<p className="text-sm font-semibold text-foreground">
 						{phase === "rejected"
 							? `${displayName} — Rejected`
 							: phase === "processing" || phase === "complete"
 								? `${displayName} — Approved`
-								: `Approve: ${displayName}`}
+								: displayName}
 					</p>
 					{phase === "processing" ? (
 						<TextShimmerLoader text="Executing..." size="sm" />
@@ -163,13 +160,24 @@ function GenericApprovalCard({
 						</p>
 					)}
 				</div>
+				{phase === "pending" && canEdit && !isEditing && (
+					<Button
+						size="sm"
+						variant="ghost"
+						className="rounded-lg text-muted-foreground -mt-1 -mr-2"
+						onClick={() => setIsEditing(true)}
+					>
+						<Pen className="size-3.5" />
+						Edit
+					</Button>
+				)}
 			</div>
 
 			{/* Description */}
 			{toolDescription && phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
-					<div className="px-5 py-2">
+					<div className="px-5 py-3">
 						<p className="text-xs text-muted-foreground">{toolDescription}</p>
 					</div>
 				</>
@@ -179,7 +187,7 @@ function GenericApprovalCard({
 			{Object.keys(args).length > 0 && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
-					<div className="px-5 py-3 space-y-2">
+					<div className="px-5 py-4 space-y-2">
 						<p className="text-xs font-medium text-muted-foreground">Parameters</p>
 						{phase === "pending" && isEditing ? (
 							<ParamEditor
@@ -200,7 +208,7 @@ function GenericApprovalCard({
 			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
-					<div className="px-5 py-3 flex items-center gap-2 select-none flex-wrap">
+					<div className="px-5 py-4 flex items-center gap-2 select-none">
 						{allowedDecisions.includes("approve") && (
 							<Button size="sm" className="rounded-lg gap-1.5" onClick={handleApprove}>
 								{isEditing && hasChanged ? "Approve with edits" : "Approve"}
@@ -210,24 +218,12 @@ function GenericApprovalCard({
 						{isMCPTool && (
 							<Button
 								size="sm"
-								variant="outline"
-								className="rounded-lg gap-1.5"
+								className="rounded-lg"
 								onClick={handleAlwaysAllow}
 							>
-								<ShieldCheckIcon className="size-3" />
 								Always Allow
 							</Button>
 						)}
-						{canEdit && !isEditing && (
-							<Button
-								size="sm"
-								variant="outline"
-								className="rounded-lg"
-								onClick={() => setIsEditing(true)}
-							>
-								Edit
-							</Button>
-						)}
 						{allowedDecisions.includes("reject") && (
 							<Button
 								size="sm"

From 3f689627722e96c2698ce023b99c8a4294eb2954 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 14 Apr 2026 04:09:30 +0530
Subject: [PATCH 28/28] feat: implement cache invalidation for MCP connectors
 upon deletion in search source connectors

---
 .../app/routes/search_source_connectors_routes.py          | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index ce19ab36d..b87ce28c9 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -636,9 +636,16 @@ async def delete_search_source_connector(
             )
 
         # Delete the connector record
+        search_space_id = db_connector.search_space_id
+        is_mcp = db_connector.connector_type == SearchSourceConnectorType.MCP_CONNECTOR
         await session.delete(db_connector)
         await session.commit()
 
+        if is_mcp:
+            from app.agents.new_chat.tools.mcp_tool import invalidate_mcp_tools_cache
+
+            invalidate_mcp_tools_cache(search_space_id)
+
         logger.info(
             f"Connector {connector_id} ({connector_name}) deleted successfully. "
             f"Total documents deleted: {total_deleted}"