feat(agent): 检索工具、模型接入与结构化回复

Agent 按组织与知识源范围调用检索工具，密钥加密保存，回复含来源与转人工意图。

backend/app/tools/faq_search.py

@@ -0,0 +1,71 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from typing import List
+from uuid import UUID
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+from app.database import SessionLocal
+from app.models.faq import FAQ
+from app.repositories.faq import FAQRepository
+
+# Word-overlap ranking beats a whole-string ILIKE here: a visitor's
+# natural-language question rarely appears verbatim in an FAQ, but shares
+# meaningful words with the right one.
+_MIN_WORD_LEN = 3
+_MAX_RESULTS = 5
+
+
+class FAQSearchTool(Toolkit):
+    """Lets the help-center answer agent search the org's PUBLISHED FAQs.
+    Read-only and org-scoped — never exposes drafts or other orgs' content."""
+
+    def __init__(self, organization_id: UUID):
+        super().__init__(name="faq_search")
+        self.organization_id = organization_id
+        self.register(self.search_faqs)
+
+    def search_faqs(self, query: str) -> str:
+        """Search this help center's published FAQs for a question.
+
+        Args:
+            query: What the visitor wants to know.
+        """
+        try:
+            with SessionLocal() as db:
+                faqs = FAQRepository(db).get_published_for_org(self.organization_id)
+                ranked = _rank(faqs, query)
+                if not ranked:
+                    return "No published FAQs matched that question."
+                return "\n\n".join(f"Q: {faq.question}\nA: {faq.answer}" for faq in ranked)
+        except Exception as e:
+            logger.error(f"FAQ search failed: {e}")
+            return "Error searching the FAQs."
+
+
+def _rank(faqs: List[FAQ], query: str) -> List[FAQ]:
+    words = {w for w in query.casefold().split() if len(w) > _MIN_WORD_LEN}
+    if not words:
+        return faqs[:_MAX_RESULTS]
+    scored = [
+        (len(words & set(f"{faq.question} {faq.answer}".casefold().split())), faq)
+        for faq in faqs
+    ]
+    scored = [(score, faq) for score, faq in scored if score > 0]
+    scored.sort(key=lambda pair: pair[0], reverse=True)
+    return [faq for _score, faq in scored[:_MAX_RESULTS]]

backend/app/tools/guardrailed_db_toolkit.py

@@ -0,0 +1,330 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Guardrailed database tools for the ticket investigation agent. One toolkit
+instance covers all of an organization's enabled DB connectors — each tool
+takes the connector name as its first argument.
+
+Layered guarantees (all enforced outside the model):
+1. sql_guardrails AST validation (SELECT-only, table allowlist, masked-column
+   references blocked, forced LIMIT, canonical re-render)
+2. read-only database session + statement timeout (db_connector_service)
+3. result-side column masking
+4. every attempt — allowed, blocked or errored — lands in
+   db_connector_audit_logs (never the result rows)
+"""
+
+import asyncio
+import time
+from typing import List, Optional
+from uuid import UUID
+
+from agno.tools import Toolkit
+
+from app.core.logger import get_logger
+from app.database import SessionLocal
+from app.models.ticket_db_connector import DBConnectorAuditLog, DBConnectorAuditOutcome
+from app.services import db_connector_service
+from app.services.db_connector_service import DBConnectorConfig
+from app.services.sql_guardrails import mask_rows, normalize_scope_map, validate_sql
+
+logger = get_logger(__name__)
+
+MAX_RESULT_CHARS = 4000
+
+# The catalogue is put in the system prompt, so it has to stay proportionate
+# to the rest of it — a connector with hundreds of allowlisted tables gets
+# trimmed and the agent falls back on list_database_tables for the rest.
+MAX_CATALOGUE_CHARS = 1500
+
+# Front-loading the catalogue saves the run a tool call: the investigator's
+# first move was otherwise always list_database_tables, spending one of its
+# max_tool_calls_per_run just to learn which tables exist (#318). agno renders
+# this into the SYSTEM message (Toolkit.instructions + add_instructions).
+_DB_TOOLKIT_INSTRUCTIONS = """<data_source name="Database">
+`query_database` reads these connectors (read-only, allowlisted tables only):
+{sources}
+Call `describe_database_table` for a table's columns before querying it. Any
+table not listed is not queryable — do not attempt it.
+</data_source>"""
+
+
+def _trim_to_line(text: str, limit: int) -> str:
+    """Trim to whole lines. Cutting mid-name would leave a half-written table
+    in the prompt that reads as a real one, and the model would spend a call
+    querying it — the exact waste this catalogue exists to avoid."""
+    if len(text) <= limit:
+        return text
+    kept, _, _ = text[:limit].rpartition("\n")
+    return (kept or "") + "\n(list truncated — call list_database_tables for the rest)"
+
+
+class GuardrailedDBTools(Toolkit):
+    """Read-only, allowlisted SQL access for AI investigations."""
+
+    def __init__(
+        self,
+        configs: List[DBConnectorConfig],
+        ticket_id: Optional[UUID] = None,
+        run_id: Optional[UUID] = None,
+    ):
+        super().__init__(name="guardrailed_database")
+        self.configs = {c.name: c for c in configs}
+        self.ticket_id = ticket_id
+        self.run_id = run_id
+        # Resolved once per run — the customer can't change mid-investigation.
+        self._scope_cache: dict = {}
+        # Evidence attribution for the investigation glass box.
+        self._connector_name = "Database"
+        self.register(self.list_database_tables)
+        self.register(self.describe_database_table)
+        self.register(self.query_database)
+        self._set_prompt_catalogue()
+
+    def _set_prompt_catalogue(self) -> None:
+        """Front-load the table catalogue into the system prompt.
+
+        Never raises: a malformed row_scope on one connector must cost this
+        prompt optimisation, not the whole toolkit — the caller
+        (_build_db_tools) turns any exception here into "no database tools at
+        all", which is far worse than one extra list_database_tables call.
+        """
+        if not self.configs:
+            return
+        try:
+            self.instructions = _DB_TOOLKIT_INSTRUCTIONS.format(
+                sources=_trim_to_line(self._source_catalogue(), MAX_CATALOGUE_CHARS)
+            )
+            self.add_instructions = True
+        except Exception as e:
+            logger.error(f"Could not build the DB catalogue for the prompt: {e}")
+
+    def _config(self, connector: str) -> Optional[DBConnectorConfig]:
+        if connector in self.configs:
+            return self.configs[connector]
+        # Tolerate case/whitespace slips from the model.
+        wanted = (connector or "").strip().lower()
+        for name, config in self.configs.items():
+            if name.strip().lower() == wanted:
+                return config
+        return None
+
+    def _scope_value(self, config: DBConnectorConfig) -> Optional[str]:
+        """The ticket customer's identifier that row-scoped tables filter by.
+
+        None when the ticket has no usable identity — an anonymous widget
+        visitor's …@noemail.com placeholder is deliberately not accepted, since
+        scoping by it would look like it worked while matching nothing. The
+        validator fails closed on None rather than dropping the filter.
+        """
+        if not config.row_scope or self.ticket_id is None:
+            return None
+        key = (config.row_scope_key or "email").lower()
+        if key in self._scope_cache:
+            return self._scope_cache[key]
+
+        try:
+            from app.models.ticket import Ticket
+            from app.repositories.customer import CustomerRepository
+
+            with SessionLocal() as db:
+                # Pin the ticket to the connector's org. On every real path they
+                # already match (the worker builds tools from the ticket's own
+                # org connectors), but this fails closed if a future caller ever
+                # pairs a ticket with another org's connector.
+                query = db.query(Ticket).filter(Ticket.id == self.ticket_id)
+                if config.organization_id is not None:
+                    query = query.filter(
+                        Ticket.organization_id == config.organization_id
+                    )
+                ticket = query.first()
+                customer = ticket.customer if ticket else None
+                value = None
+                if customer is not None:
+                    if key == "phone":
+                        value = (customer.phone or "").strip() or None
+                    else:
+                        value = CustomerRepository.display_email(customer.email)
+        except Exception as e:
+            # Don't cache a transient failure — a later query in the same run
+            # should retry, not stay permanently blocked. validate_sql fails
+            # closed on the None returned here, so this never opens a table up.
+            logger.error(f"Row-scope lookup failed for ticket {self.ticket_id}: {e}")
+            return None
+
+        self._scope_cache[key] = value
+        return value
+
+    def _unknown(self, connector: str) -> str:
+        return (
+            f"Unknown database connector '{connector}'. "
+            f"Available: {', '.join(self.configs) or 'none'}"
+        )
+
+    def _audit(
+        self,
+        config: DBConnectorConfig,
+        raw_sql: str,
+        outcome: str,
+        validated_sql: Optional[str] = None,
+        block_reason: Optional[str] = None,
+        row_count: Optional[int] = None,
+        duration_ms: Optional[int] = None,
+    ) -> None:
+        try:
+            with SessionLocal() as db:
+                db.add(
+                    DBConnectorAuditLog(
+                        connector_id=config.id,
+                        organization_id=config.organization_id,
+                        ticket_id=self.ticket_id,
+                        run_id=self.run_id,
+                        raw_sql=raw_sql[:10000],
+                        validated_sql=validated_sql,
+                        outcome=outcome,
+                        block_reason=block_reason,
+                        row_count=row_count,
+                        duration_ms=duration_ms,
+                    )
+                )
+                db.commit()
+        except Exception as e:
+            logger.error(f"DB connector audit write failed: {e}")
+
+    async def list_database_tables(self) -> str:
+        """List the database connectors you may query and the tables each one
+        allows. Access is read-only; only these tables are queryable."""
+        return self._source_catalogue()
+
+    def _source_catalogue(self) -> str:
+        """The connector/table catalogue, as both the tool result and the
+        toolkit's system-prompt instructions. Sync so __init__ can use it."""
+        if not self.configs:
+            return "No database connectors are configured."
+        lines = []
+        for config in self.configs.values():
+            scoped = normalize_scope_map(config.row_scope)
+            tables = []
+            for table in config.allowed_tables or []:
+                key = (table or "").strip().lower()
+                column = scoped.get(key) or scoped.get(key.rpartition(".")[2])
+                # Say so up front: the agent should not waste a tool call
+                # trying to widen a scoped table, or read across customers.
+                tables.append(
+                    f"{table} (auto-scoped to this ticket's customer by {column})"
+                    if column else table
+                )
+            listed = ", ".join(tables) or "(no tables allowlisted)"
+            lines.append(f"{config.name} [{config.engine}]: {listed}")
+        return "\n".join(lines)
+
+    async def describe_database_table(self, connector: str, table: str) -> str:
+        """Get the columns and types of an allowlisted table.
+
+        Args:
+            connector: The connector name from list_database_tables.
+            table: Table name, optionally schema-qualified (schema.table).
+        """
+        config = self._config(connector)
+        if config is None:
+            return self._unknown(connector)
+        allowed = {t.strip().lower() for t in config.allowed_tables or []}
+        wanted = (table or "").strip().lower()
+        match = next(
+            (t for t in allowed if t == wanted or t.endswith(f".{wanted}")), None
+        )
+        if match is None:
+            return f"Table '{table}' is not on this connector's allowlist."
+        schema, _, name = match.rpartition(".")
+        schema = schema or ("public" if config.engine != "mysql" else config.database)
+        try:
+            columns = await asyncio.to_thread(
+                db_connector_service.describe_columns, config, schema, name
+            )
+        except Exception as e:
+            return f"Failed to describe table: {e}"
+        masked = {c.strip().lower() for c in config.masked_columns or []}
+        lines = [
+            f"- {col['name']} ({col['type']})"
+            + (" [MASKED — cannot be queried]" if col["name"].lower() in masked else "")
+            for col in columns
+        ]
+        scoped = normalize_scope_map(config.row_scope)
+        scope_column = scoped.get(match) or scoped.get(name)
+        note = (
+            f"\nThis table is automatically restricted to rows where "
+            f"{scope_column} is this ticket's customer — you will only ever see "
+            f"their own rows, so no customer filter is needed in your query."
+            if scope_column else ""
+        )
+        return f"Columns of {match}:\n" + "\n".join(lines) + note
+
+    async def query_database(self, connector: str, sql: str) -> str:
+        """Run a read-only SQL SELECT against an allowlisted database.
+
+        Only single SELECT statements over allowlisted tables are permitted —
+        writes are impossible. Results are row-limited and masked columns are
+        redacted. Prefer precise WHERE clauses over broad scans.
+
+        Args:
+            connector: The connector name from list_database_tables.
+            sql: One SELECT statement.
+        """
+        config = self._config(connector)
+        if config is None:
+            return self._unknown(connector)
+
+        verdict = validate_sql(
+            sql,
+            config.allowed_tables,
+            config.max_rows,
+            engine=config.engine,
+            masked_columns=config.masked_columns,
+            row_scope=config.row_scope,
+            scope_value=self._scope_value(config),
+            # Only emails: a phone is digits, so folding case buys nothing and
+            # would cost the index on the column.
+            scope_case_insensitive=(config.row_scope_key or "email").lower() == "email",
+        )
+        if not verdict.ok:
+            self._audit(
+                config, sql, DBConnectorAuditOutcome.BLOCKED.value,
+                block_reason=verdict.reason,
+            )
+            return f"Query blocked by guardrails: {verdict.reason}"
+
+        started = time.monotonic()
+        try:
+            columns, rows = await asyncio.to_thread(
+                db_connector_service.run_readonly_query, config, verdict.sql
+            )
+        except Exception as e:
+            duration_ms = int((time.monotonic() - started) * 1000)
+            self._audit(
+                config, sql, DBConnectorAuditOutcome.ERROR.value,
+                validated_sql=verdict.sql, block_reason=str(e)[:2000],
+                duration_ms=duration_ms,
+            )
+            return f"Query failed: {e}"
+
+        duration_ms = int((time.monotonic() - started) * 1000)
+        rows = mask_rows(columns, rows, config.masked_columns)
+        self._audit(
+            config, sql, DBConnectorAuditOutcome.ALLOWED.value,
+            validated_sql=verdict.sql, row_count=len(rows), duration_ms=duration_ms,
+        )
+        return db_connector_service.format_result_table(
+            columns, rows, config.max_rows
+        )[:MAX_RESULT_CHARS]

backend/app/tools/jira_toolkit.py

@@ -0,0 +1,726 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from typing import Optional, Dict, Any, List
+from agno.tools import Toolkit
+from app.core.config import settings
+from app.core.logger import get_logger
+from app.services.jira import (
+    JiraService,
+    jira_accessible_resources_url,
+    jira_rest_url,
+    jira_token_url,
+)
+from app.repositories.session_to_agent import SessionToAgentRepository
+from app.api.jira import CreateJiraIssueModel
+from app.database import SessionLocal
+from app.models.organization import Organization
+from app.models.agent import Agent
+from uuid import UUID
+
+logger = get_logger(__name__)
+
+class JiraTools(Toolkit):
+    def __init__(self, agent_id: str, org_id: str, session_id: str):
+        super().__init__(name="jira_tools")
+        self.agent_id = agent_id
+        self.org_id = org_id
+        self.session_id = session_id
+        self.jira_service = JiraService()
+        
+        # Register the functions
+        self.register(self.create_jira_ticket)
+        self.register(self.get_ticket_status)
+        self.register(self.check_existing_ticket)
+    
+    def create_jira_ticket(
+        self, 
+        summary: str, 
+        description: str, 
+        priority: Optional[str] = "Medium"
+    ) -> str:
+        """
+        Create a Jira ticket for the current session or update an existing one.
+        
+        Args:
+            summary (str): The summary/title of the ticket.
+            description (str): The detailed description of the ticket.
+            priority (str, optional): The priority level of the ticket (Highest, High, Medium, Low, Lowest). Defaults to "Medium".
+            
+        Returns:
+            str: JSON string with information about the created or updated ticket including ticket ID and status.
+        """
+        try:
+            import json
+            import requests
+            from datetime import datetime, timedelta
+            
+            # Check if a ticket already exists for this session
+            existing_ticket_str = self.check_existing_ticket()
+            existing_ticket = json.loads(existing_ticket_str)
+            existing_ticket_id = None
+            is_update = False
+            
+            if existing_ticket.get("exists", False):
+                existing_ticket_id = existing_ticket.get("ticket_id")
+                is_update = True
+                logger.info(f"Found existing ticket {existing_ticket_id} for session {self.session_id}, will update it")
+            
+            # Use context manager for database operations
+            with SessionLocal() as db:
+                # Get the agent's Jira configuration
+                try:
+                    agent_uuid = UUID(str(self.agent_id))
+                    agent = db.query(Agent).filter(Agent.id == agent_uuid).first()
+                except (ValueError, TypeError) as e:
+                    logger.error(f"Invalid agent ID format: {e}")
+                    return json.dumps({
+                        "success": False,
+                        "message": f"Invalid agent ID format: {str(e)}"
+                    })
+                    
+                if not agent:
+                    return json.dumps({
+                        "success": False,
+                        "message": "Agent not found"
+                    })
+                    
+                # Get the organization
+                try:
+                    org_uuid = UUID(str(self.org_id))
+                    organization = db.query(Organization).filter(
+                            Organization.id == org_uuid
+                    ).first()
+                except (ValueError, TypeError) as e:
+                    logger.error(f"Invalid organization ID format: {e}")
+                    return json.dumps({
+                        "success": False,
+                        "message": f"Invalid organization ID format: {str(e)}"
+                    })
+            
+                
+                if not organization:
+                    return json.dumps({
+                        "success": False,
+                        "message": "Organization not found"
+                    })
+                
+                # Get the agent's Jira configuration
+                from app.models.jira import AgentJiraConfig
+                jira_config = db.query(AgentJiraConfig).filter(
+                    AgentJiraConfig.agent_id == str(self.agent_id)
+                ).first()
+                
+                if not jira_config or not jira_config.enabled:
+                    return json.dumps({
+                        "success": False,
+                        "message": "Jira integration is not enabled for this agent"
+                    })
+                    
+                # Create the issue data
+                issue_data = CreateJiraIssueModel(
+                    projectKey=jira_config.project_key,
+                    issueTypeId=jira_config.issue_type_id,
+                    summary=summary,
+                    description=description,
+                    priority=priority,
+                    chatId=str(self.session_id)  # Ensure session_id is a string
+                )
+                
+                # Get the Jira token
+                from app.models.jira import JiraToken
+                token = db.query(JiraToken).filter(
+                    JiraToken.organization_id == organization.id
+                ).first()
+                
+                if not token:
+                    return json.dumps({
+                        "success": False,
+                        "message": "No Jira connection found"
+                    })
+            
+            # Check if token is valid and refresh if needed
+            is_valid = self.jira_service.validate_token(token)
+            if not is_valid:
+                # Implement synchronous token refresh
+                try:
+                    client_id = settings.JIRA_CLIENT_ID
+                    client_secret = settings.JIRA_CLIENT_SECRET
+                    
+                    if not client_id or not client_secret:
+                        return json.dumps({
+                            "success": False,
+                            "message": "Jira client credentials not configured"
+                        })
+                    
+                    # Refresh token using requests
+                    refresh_data = {
+                        "grant_type": "refresh_token",
+                        "client_id": client_id,
+                        "client_secret": client_secret,
+                        "refresh_token": token.refresh_token
+                    }
+                    
+                    refresh_response = requests.post(
+                        jira_token_url(),
+                        data=refresh_data
+                    )
+                    
+                    if refresh_response.status_code != 200:
+                        logger.error(f"Failed to refresh token: {refresh_response.text}")
+                        return json.dumps({
+                            "success": False,
+                            "message": f"Failed to refresh Jira token: {refresh_response.text}"
+                        })
+                    
+                    # Parse response and update token
+                    token_data = refresh_response.json()
+                    
+                    # Update token in database
+                    token.access_token = token_data["access_token"]
+                    token.refresh_token = token_data.get("refresh_token", token.refresh_token)
+                    token.token_type = token_data["token_type"]
+                    token.expires_at = datetime.utcnow() + timedelta(seconds=token_data["expires_in"])
+                    
+                    db.commit()
+                    logger.info("Successfully refreshed Jira token")
+                    
+                except Exception as e:
+                    logger.error(f"Error refreshing Jira token: {e}")
+                    return json.dumps({
+                        "success": False,
+                        "message": f"Error refreshing Jira token: {str(e)}"
+                    })
+            
+            # Create the issue directly using the REST API
+            headers = {
+                "Authorization": f"Bearer {token.access_token}",
+                "Accept": "application/json",
+                "Content-Type": "application/json"
+            }
+            
+            # Check if priority field is available for this project and issue type
+            priority_available = False
+            try:
+                # Get the create metadata to check available fields
+                create_meta_url = jira_rest_url(str(token.cloud_id), f"issue/createmeta?projectKeys={issue_data.projectKey}&issuetypeIds={issue_data.issueTypeId}&expand=projects.issuetypes.fields")
+                meta_response = requests.get(create_meta_url, headers=headers)
+                
+                if meta_response.status_code == 200:
+                    meta_data = meta_response.json()
+                    # Navigate through the response to find the priority field
+                    if meta_data.get("projects") and len(meta_data["projects"]) > 0:
+                        project = meta_data["projects"][0]
+                        if project.get("issuetypes") and len(project["issuetypes"]) > 0:
+                            issue_type = project["issuetypes"][0]
+                            if issue_type.get("fields") and "priority" in issue_type["fields"]:
+                                priority_available = True
+                                logger.info("Priority field is available for this project and issue type")
+            except Exception as e:
+                logger.warning(f"Failed to check if priority field is available: {e}")
+                # Continue without setting priority
+            
+            # Prepare the issue data for the API
+            api_data = {
+                "fields": {
+                    "summary": issue_data.summary,
+                    "description": {
+                        "type": "doc",
+                        "version": 1,
+                        "content": [
+                            {
+                                "type": "paragraph",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": issue_data.description
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                }
+            }
+            
+            # Only include project and issuetype for new tickets, not updates
+            if not is_update:
+                api_data["fields"]["project"] = {"key": issue_data.projectKey}
+                api_data["fields"]["issuetype"] = {"id": issue_data.issueTypeId}
+            
+            # Add priority if provided and available
+            if priority_available and issue_data.priority:
+                # Map string priority to Jira priority
+                priority_map = {
+                    "Highest": "1",
+                    "High": "2",
+                    "Medium": "3",
+                    "Low": "4",
+                    "Lowest": "5"
+                }
+                priority_id = priority_map.get(issue_data.priority, "3")  # Default to Medium
+                api_data["fields"]["priority"] = {"id": priority_id}
+                logger.info(f"Setting priority to {issue_data.priority} (ID: {priority_id})")
+            else:
+                logger.info("Priority field is not available or not provided, skipping")
+            
+            try:
+                if is_update:
+                    # Get the existing ticket details first to get the current description
+                    existing_ticket_url = jira_rest_url(str(token.cloud_id), f"issue/{existing_ticket_id}")
+                    existing_ticket_response = requests.get(existing_ticket_url, headers=headers)
+                    
+                    if existing_ticket_response.status_code == 200:
+                        existing_ticket_data = existing_ticket_response.json()
+                        existing_description = ""
+                        
+                        # Extract the existing description text
+                        if existing_ticket_data.get("fields", {}).get("description"):
+                            description_field = existing_ticket_data["fields"]["description"]
+                            if isinstance(description_field, dict) and description_field.get("content"):
+                                # Extract text from Atlassian Document Format
+                                for content in description_field.get("content", []):
+                                    if content.get("type") == "paragraph" and content.get("content"):
+                                        for text_node in content.get("content", []):
+                                            if text_node.get("type") == "text":
+                                                existing_description += text_node.get("text", "")
+                                        existing_description += "\n\n"
+                            elif isinstance(description_field, str):
+                                existing_description = description_field
+                        
+                        # Append the new description to the existing one
+                        combined_description = existing_description.strip()
+                        if combined_description:
+                            combined_description += "\n\n--- Update " + datetime.now().strftime("%Y-%m-%d %H:%M:%S") + " ---\n\n"
+                        combined_description += description
+                        
+                        # Update the description in the API data
+                        api_data["fields"]["description"] = {
+                            "type": "doc",
+                            "version": 1,
+                            "content": [
+                                {
+                                    "type": "paragraph",
+                                    "content": [
+                                        {
+                                            "type": "text",
+                                            "text": combined_description
+                                        }
+                                    ]
+                                }
+                            ]
+                        }
+                        
+                        logger.info(f"Appending new description to existing ticket {existing_ticket_id}")
+                    else:
+                        error_msg = f"Failed to get existing ticket details: {existing_ticket_response.text}"
+                        logger.warning(error_msg)
+                        return json.dumps({
+                            "success": False,
+                            "message": error_msg
+                        })
+                    
+                    # Update existing ticket
+                    url = jira_rest_url(str(token.cloud_id), f"issue/{existing_ticket_id}")
+                    response = requests.put(url, headers=headers, json=api_data)
+                    
+                    if response.status_code not in (200, 204):
+                        return json.dumps({
+                            "success": False,
+                            "message": f"Failed to update Jira ticket: {response.text}"
+                        })
+                    
+                    # Get updated ticket details
+                    get_response = requests.get(url, headers=headers)
+                    if get_response.status_code != 200:
+                        logger.warning(f"Failed to get updated ticket details: {get_response.text}")
+                        issue_result = {"key": existing_ticket_id}
+                    else:
+                        issue_result = get_response.json()
+                    
+                    action_message = "updated"
+                else:
+                    # Create new ticket
+                    url = jira_rest_url(str(token.cloud_id), "issue")
+                    response = requests.post(url, headers=headers, json=api_data)
+                    
+                    if response.status_code not in (200, 201):
+                        return json.dumps({
+                            "success": False,
+                            "message": f"Failed to create Jira ticket: {response.text}"
+                        })
+                    
+                    issue_result = response.json()
+                    action_message = "created"
+                
+                # Get the site URL from the token
+                site_url = token.site_url
+                if not site_url:
+                    # Try to get the domain from the token
+                    domain = token.domain
+                    if domain:
+                        site_url = f"https://{domain}.atlassian.net"
+                    else:
+                        # Try to get the site URL from the cloud resources
+                        try:
+                            resources_url = jira_accessible_resources_url()
+                            resources_response = requests.get(resources_url, headers={
+                                "Authorization": f"Bearer {token.access_token}",
+                                "Accept": "application/json"
+                            })
+                            
+                            if resources_response.status_code == 200:
+                                resources = resources_response.json()
+                                for resource in resources:
+                                    if resource.get("id") == str(token.cloud_id):
+                                        site_url = resource.get("url", "")
+                                        break
+                        except Exception as e:
+                            logger.warning(f"Failed to get site URL from resources: {e}")
+                
+                # Construct the ticket URL
+                ticket_key = issue_result["key"]
+                if site_url:
+                    # Remove trailing slash if present
+                    if site_url.endswith("/"):
+                        site_url = site_url[:-1]
+                    
+                    # Construct the URL using the site URL
+                    ticket_url = f"{site_url}/browse/{ticket_key}"
+                else:
+                    # Get the organization name for the URL
+                    org_name = organization.name.lower().replace(" ", "-") if organization.name else "organization"
+                    # Use the Atlassian Cloud URL format
+                    ticket_url = f"https://{org_name}.atlassian.net/browse/{ticket_key}"
+                
+                # Update the session with ticket information
+                session_repo = SessionToAgentRepository(db)
+                try:
+                    # Use the combined description for updates, or just the new description for new tickets
+                    final_description = combined_description if is_update and 'combined_description' in locals() else description
+                    
+                    session_repo.update_session(
+                            str(self.session_id),  # Ensure session_id is a string
+                        {
+                            "ticket_id": issue_result["key"],
+                                "ticket_status": "Updated" if is_update else "Created",
+                            "ticket_summary": summary,
+                                "ticket_description": final_description,
+                            "integration_type": "JIRA",
+                                "ticket_priority": priority if priority_available else None,
+                                "ticket_url": ticket_url
+                        }
+                    )
+                except Exception as e:
+                    logger.error(f"Failed to update session with ticket information: {e}")
+                    # Continue since the ticket was created/updated successfully
+                
+                return json.dumps({
+                    "success": True,
+                    "message": f"Ticket {action_message} successfully: {issue_result['key']}",
+                    "ticket_id": issue_result["key"],
+                    "ticket_url": ticket_url,
+                    "was_updated": is_update
+                })
+                
+            except requests.exceptions.RequestException as e:
+                logger.error(f"Request error {'updating' if is_update else 'creating'} Jira ticket: {e}")
+                return json.dumps({
+                    "success": False,
+                    "message": f"Request error {'updating' if is_update else 'creating'} Jira ticket: {str(e)}"
+                })
+                
+        except Exception as e:
+            logger.error(f"Error {'updating' if 'is_update' in locals() and is_update else 'creating'} Jira ticket: {str(e)}")
+            return json.dumps({
+                "success": False,
+                "message": f"Error {'updating' if 'is_update' in locals() and is_update else 'creating'} Jira ticket: {str(e)}"
+            })
+    
+    def get_ticket_status(self, ticket_id: Optional[str] = None) -> str:
+        """
+        Get the status of a Jira ticket.
+        
+        Args:
+            ticket_id (str, optional): The ID of the ticket to check. If not provided, will check for a ticket associated with the current session.
+            
+        Returns:
+            str: JSON string with information about the ticket including its status.
+        """
+        try:
+            import json
+            import requests
+            from datetime import datetime, timedelta
+            
+            # Use context manager for database operations
+            with SessionLocal() as db:
+                # If no ticket ID is provided, check if there's a ticket for this session
+                if not ticket_id:
+                    session_repo = SessionToAgentRepository(db)
+                    try:
+                        session = session_repo.get_session(str(self.session_id))
+                    except Exception as e:
+                        logger.error(f"Failed to get session: {e}")
+                        return json.dumps({
+                            "success": False,
+                            "message": f"Failed to get session: {str(e)}"
+                        })
+                    
+                    if not session or not session.ticket_id:
+                        return json.dumps({
+                            "success": False,
+                            "message": "No ticket found for this session"
+                        })
+                        
+                    ticket_id = session.ticket_id
+                
+                # Get the organization
+                try:
+                    org_uuid = UUID(str(self.org_id))
+                    organization = db.query(Organization).filter(
+                            Organization.id == org_uuid
+                    ).first()
+                except (ValueError, TypeError) as e:
+                    logger.error(f"Invalid organization ID format: {e}")
+                    return json.dumps({
+                        "success": False,
+                        "message": f"Invalid organization ID format: {str(e)}"
+                    })
+                
+                if not organization:
+                    return json.dumps({
+                        "success": False,
+                        "message": "Organization not found"
+                    })
+                
+                # Get the ticket status from Jira
+                from app.models.jira import JiraToken
+                token = db.query(JiraToken).filter(
+                    JiraToken.organization_id == organization.id
+                ).first()
+                
+                if not token:
+                    return json.dumps({
+                        "success": False,
+                        "message": "No Jira connection found"
+                    })
+            
+            # Check if token is valid and refresh if needed
+            is_valid = self.jira_service.validate_token(token)
+            if not is_valid:
+                # Implement synchronous token refresh
+                try:
+                    client_id = settings.JIRA_CLIENT_ID
+                    client_secret = settings.JIRA_CLIENT_SECRET
+                    
+                    if not client_id or not client_secret:
+                        return json.dumps({
+                            "success": False,
+                            "message": "Jira client credentials not configured"
+                        })
+                    
+                    # Refresh token using requests
+                    refresh_data = {
+                        "grant_type": "refresh_token",
+                        "client_id": client_id,
+                        "client_secret": client_secret,
+                        "refresh_token": token.refresh_token
+                    }
+                    
+                    refresh_response = requests.post(
+                        jira_token_url(),
+                        data=refresh_data
+                    )
+                    
+                    if refresh_response.status_code != 200:
+                        logger.error(f"Failed to refresh token: {refresh_response.text}")
+                        return json.dumps({
+                            "success": False,
+                            "message": f"Failed to refresh Jira token: {refresh_response.text}"
+                        })
+                    
+                    # Parse response and update token
+                    token_data = refresh_response.json()
+                    
+                    # Update token in database
+                    token.access_token = token_data["access_token"]
+                    token.refresh_token = token_data.get("refresh_token", token.refresh_token)
+                    token.token_type = token_data["token_type"]
+                    token.expires_at = datetime.utcnow() + timedelta(seconds=token_data["expires_in"])
+                    
+                    db.commit()
+                    logger.info("Successfully refreshed Jira token")
+                    
+                except Exception as e:
+                    logger.error(f"Error refreshing Jira token: {e}")
+                    return json.dumps({
+                        "success": False,
+                        "message": f"Error refreshing Jira token: {str(e)}"
+                    })
+            
+            # Get the issue
+            headers = {
+                "Authorization": f"Bearer {token.access_token}",
+                "Accept": "application/json"
+            }
+            
+            # Ensure ticket_id is a string before using it in the URL
+            ticket_id_str = str(ticket_id) if ticket_id else ""
+            
+            url = jira_rest_url(str(token.cloud_id), f"issue/{ticket_id_str}")
+            
+            try:
+                response = requests.get(url, headers=headers)
+            except requests.exceptions.RequestException as e:
+                logger.error(f"Failed to make request to Jira API: {e}")
+                return json.dumps({
+                    "success": False,
+                    "message": f"Failed to make request to Jira API: {str(e)}"
+                })
+            
+            if response.status_code != 200:
+                return json.dumps({
+                    "success": False,
+                    "message": f"Failed to get Jira ticket: {response.text}"
+                })
+                
+            try:
+                issue_data = response.json()
+            except ValueError as e:
+                logger.error(f"Failed to parse Jira response: {e}")
+                return json.dumps({
+                    "success": False,
+                    "message": f"Failed to parse Jira response: {str(e)}"
+                })
+            
+            # Get the site URL from the token
+            site_url = token.site_url
+            if not site_url:
+                # Try to get the domain from the token
+                domain = token.domain
+                if domain:
+                    site_url = f"https://{domain}.atlassian.net"
+                else:
+                    # Try to get the site URL from the cloud resources
+                    try:
+                        resources_url = jira_accessible_resources_url()
+                        resources_response = requests.get(resources_url, headers={
+                            "Authorization": f"Bearer {token.access_token}",
+                            "Accept": "application/json"
+                        })
+                        
+                        if resources_response.status_code == 200:
+                            resources = resources_response.json()
+                            for resource in resources:
+                                if resource.get("id") == str(token.cloud_id):
+                                    site_url = resource.get("url", "")
+                                    break
+                    except Exception as e:
+                        logger.warning(f"Failed to get site URL from resources: {e}")
+            
+            # Construct the ticket URL
+            if site_url:
+                # Remove trailing slash if present
+                if site_url.endswith("/"):
+                    site_url = site_url[:-1]
+                
+                # Construct the URL using the site URL
+                ticket_url = f"{site_url}/browse/{ticket_id_str}"
+            else:
+                # Get the organization name for the URL
+                org_name = organization.name.lower().replace(" ", "-") if organization.name else "organization"
+                # Use the Atlassian Cloud URL format
+                ticket_url = f"https://{org_name}.atlassian.net/browse/{ticket_id_str}"
+            
+            return json.dumps({
+                "success": True,
+                "ticket_id": ticket_id_str,
+                "ticket_status": issue_data.get("fields", {}).get("status", {}).get("name", "Unknown"),
+                "ticket_summary": issue_data.get("fields", {}).get("summary", ""),
+                "ticket_description": issue_data.get("fields", {}).get("description", ""),
+                "ticket_priority": issue_data.get("fields", {}).get("priority", {}).get("name", ""),
+                "ticket_url": ticket_url
+            })
+        except Exception as e:
+            logger.error(f"Error getting Jira ticket status: {str(e)}")
+            return json.dumps({
+                "success": False,
+                "message": f"Error getting Jira ticket status: {str(e)}"
+            })
+    
+    def check_existing_ticket(self) -> str:
+        """
+        Check if a Jira ticket already exists for the current session.
+        
+        Returns:
+            str: JSON string with information about whether a ticket exists.
+        """
+        try:
+            import json
+            
+            # Use context manager for database operations
+            with SessionLocal() as db:
+                # Get the session
+                session_repo = SessionToAgentRepository(db)
+                try:
+                    session = session_repo.get_session(str(self.session_id))
+                except Exception as e:
+                    logger.error(f"Failed to get session: {e}")
+                    return json.dumps({
+                        "exists": False,
+                        "message": f"Failed to get session: {str(e)}"
+                    })
+                
+                if not session or not session.ticket_id:
+                    return json.dumps({
+                        "exists": False,
+                        "message": "No ticket found for this session"
+                    })
+                
+            # Get the ticket status
+            ticket_status_str = self.get_ticket_status(session.ticket_id)
+            ticket_status = json.loads(ticket_status_str)
+            
+            if not ticket_status.get("success", False):
+                return json.dumps({
+                    "exists": True,
+                    "ticket_id": session.ticket_id,
+                    "ticket_status": session.ticket_status,
+                    "ticket_summary": session.ticket_summary,
+                    "ticket_description": session.ticket_description,
+                    "ticket_priority": session.ticket_priority,
+                    "message": "Ticket exists in the database but could not be retrieved from Jira"
+                })
+                
+            return json.dumps({
+                "exists": True,
+                "ticket_id": ticket_status.get("ticket_id"),
+                "ticket_status": ticket_status.get("ticket_status"),
+                "ticket_summary": ticket_status.get("ticket_summary"),
+                "ticket_description": ticket_status.get("ticket_description"),
+                "ticket_priority": ticket_status.get("ticket_priority"),
+                "ticket_url": ticket_status.get("ticket_url"),
+                "message": "Ticket exists"
+            })
+        except Exception as e:
+            logger.error(f"Error checking existing ticket: {str(e)}")
+            return json.dumps({
+                "exists": False,
+                "message": f"Error checking existing ticket: {str(e)}"
+            })
+    
+    # Private async methods that will be called by the public synchronous methods
+    
+    # Note: We've removed the async _check_existing_ticket method and replaced it with a synchronous implementation 

backend/app/tools/knowledge_search_byagent.py

@@ -0,0 +1,307 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import traceback
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+from agno.tools import Toolkit
+from agno.utils.log import logger
+from sqlalchemy import text
+from app.database import SessionLocal
+from app.core.config import settings
+from app.knowledge.chunking import chunk_id, page_id_of, split_text
+from app.repositories.knowledge import KnowledgeRepository
+from agno.knowledge.agent import AgentKnowledge
+from agno.vectordb.pgvector import PgVector, SearchType
+from app.knowledge.embedder import get_embedder
+from uuid import UUID
+
+NO_RESULTS = "No relevant information found in the knowledge base."
+NO_FURTHER_RESULTS = (
+    "No further results for this topic in the knowledge base beyond what earlier "
+    "searches in this turn already returned."
+)
+
+
+class _Hit:
+    """One chunk row as rendered to the model, plus what groups and orders it."""
+
+    __slots__ = ("id", "content", "page_id", "chunk", "chunk_count", "url", "name")
+
+    def __init__(self, id: str, content: str, meta: Dict[str, Any], name: str):
+        self.id = id
+        self.content = content
+        self.name = name
+        self.page_id = meta.get("page_id") or page_id_of(id)
+        self.chunk = meta.get("chunk") if isinstance(meta.get("chunk"), int) else None
+        self.chunk_count = meta.get("chunk_count") if isinstance(meta.get("chunk_count"), int) else None
+        self.url = meta.get("url")
+
+    @property
+    def is_chunked(self) -> bool:
+        return self.chunk is not None and self.chunk_count is not None and self.chunk_count > 1
+
+
+class KnowledgeSearchByAgent(Toolkit):
+    def __init__(self, agent_id: str, org_id: UUID, source: str = None):
+        super().__init__(name="knowledge_search_by_agent")
+        self.name = "knowledge_search_by_agent"
+        self.description = "Search the knowledge base for information about a query"
+        self.function = self.search_knowledge_base
+        self.agent_id = agent_id
+        self.org_id = org_id
+        self.source = source
+        # Structured citations for the most recent turn: list of {"name", "type"}.
+        # Read (and reset) by the chat agent after each run to attach to the response.
+        self.collected_sources: List[Dict[str, str]] = []
+        # Chunk ids already shown to the model this turn. A repeat search skips
+        # them and returns the next-best material instead of the same text again,
+        # so every tool call within the turn's budget adds something new.
+        self.seen_chunk_ids: Set[str] = set()
+
+        # NOTE: this used to export the org's key as OPENAI_API_KEY for agno's
+        # old default OpenAI embedder. Search now uses the local FastEmbed
+        # embedder and every model gets its key explicitly, so the env write
+        # was dead — and a cross-tenant race (concurrent orgs overwrote each
+        # other's key in process-global state).
+        self.agent_knowledge = None
+        self._table: Optional[str] = None
+        self._schema: Optional[str] = None
+        self.register(self.search_knowledge_base)
+
+    def reset_turn(self) -> None:
+        """Forget this turn's citations and shown chunks before the next run."""
+        self.collected_sources = []
+        self.seen_chunk_ids = set()
+
+    def search_knowledge_base(self, query: str) -> str:
+        """Use this function to search the knowledge base for information about a query.
+
+        Args:
+            query: The query to search for.
+        """
+        try:
+            logger.debug(f"Searching knowledge base for query: {query}")
+
+            # Use context manager for database operations
+            with SessionLocal() as db:
+                knowledge_repo = KnowledgeRepository(db)
+                # Get knowledge sources linked to this agent
+                knowledge_sources = knowledge_repo.get_by_agent(self.agent_id)
+
+                if not knowledge_sources:
+                    return "No knowledge sources available for this agent."
+
+                # All of an agent's sources live in the org's one vector table.
+                source = knowledge_sources[0]
+                self._table = source.table_name
+                self._schema = source.schema
+
+                # Initialize agent_knowledge if it doesn't exist
+                if self.agent_knowledge is None:
+                    # Initialize vector db with simpler search type to avoid connection issues
+                    vector_db = PgVector(
+                        table_name=source.table_name,
+                        db_url=settings.DATABASE_URL,
+                        schema=source.schema,
+                        search_type=SearchType.vector,  # Changed from hybrid to vector for speed
+                        embedder=get_embedder()
+                    )
+                    logger.debug(f"Vector db initialized: {source.table_name}")
+
+                    # Create AgentKnowledge instance
+                    self.agent_knowledge = AgentKnowledge(vector_db=vector_db)
+
+                # Convert UUID to string in filters
+                filters = {"agent_id": [str(self.agent_id)]}
+                if self.source:
+                    filters["name"] = self.source
+                logger.debug(f"Search filters: {filters}")
+
+                # Ask for enough rows that, after skipping what this turn has
+                # already shown, a full set of new ones remains.
+                limit = settings.KNOWLEDGE_SEARCH_RESULTS
+                documents = self.agent_knowledge.search(
+                    query=query,
+                    num_documents=limit + len(self.seen_chunk_ids),
+                    filters=filters
+                )
+                logger.debug(f"Documents: {documents}")
+
+                hits = [
+                    _Hit(
+                        getattr(doc, "id", None) or f"{doc.name}#{position}",
+                        doc.content,
+                        getattr(doc, "meta_data", None) or {},
+                        doc.name or "Untitled",
+                    )
+                    for position, doc in enumerate(documents)
+                    if doc.content
+                ]
+                fresh = [hit for hit in hits if hit.id not in self.seen_chunk_ids][:limit]
+                if not fresh:
+                    return NO_FURTHER_RESULTS if hits else NO_RESULTS
+
+                hits_by_id = {hit.id: hit for hit in fresh}
+                neighbours, heads = self._page_context(db, fresh)
+                for hit in neighbours:
+                    hits_by_id.setdefault(hit.id, hit)
+
+                source_types = {
+                    source.source: source.source_type.value.lower() for source in knowledge_sources
+                }
+                rendered, shown = self._render(hits_by_id.values(), heads, source_types)
+                # Only what the model actually received counts as seen or as a
+                # citation; a page dropped by the size cap stays searchable.
+                self.seen_chunk_ids.update(hit.id for hit in shown)
+                self._record_sources(shown, source_types)
+                return rendered
+
+        except Exception as e:
+            logger.error(f"Error searching knowledge base: {str(e)}")
+            logger.error(f"Full traceback: {traceback.format_exc()}")
+            return "Error searching knowledge base."
+
+    def _page_context(self, db, hits: List[_Hit]) -> Tuple[List[_Hit], Dict[str, _Hit]]:
+        """Context for each hit on a chunked page, fetched in one query.
+
+        Neighbours — the chunk before and after a hit — so a fact split by a
+        chunk boundary (a pricing table, a numbered procedure) arrives whole.
+
+        Heads — the page's first chunk, keyed by page id — which is where a
+        page says what it is: a product's name and price, a plan's headline
+        terms. A query that matches the description further down (or is
+        phrased in another language than the page) would otherwise come back
+        without them. Heads are optional: ``_render`` adds them only where
+        they fit after every matched page has its place.
+
+        Only chunked pages have context; a single-row page is complete."""
+        neighbour_ids: Set[str] = set()
+        head_ids: Set[str] = set()
+        for hit in hits:
+            if not hit.is_chunked:
+                continue
+            for index in (hit.chunk - 1, hit.chunk + 1):
+                if 1 <= index <= hit.chunk_count:
+                    neighbour_ids.add(chunk_id(hit.page_id, index))
+            head_ids.add(chunk_id(hit.page_id, 1))
+        known = self.seen_chunk_ids | {hit.id for hit in hits}
+        neighbour_ids -= known
+        head_ids -= known | neighbour_ids
+        wanted = neighbour_ids | head_ids
+        if not wanted:
+            return [], {}
+
+        rows = db.execute(
+            text(
+                f'SELECT id, name, content, meta_data FROM {self._schema}."{self._table}" '
+                "WHERE id = ANY(:ids)"
+            ),
+            {"ids": list(wanted)},
+        ).fetchall()
+        fetched = [_Hit(row.id, row.content, row.meta_data or {}, row.name or "Untitled") for row in rows]
+        neighbours = [hit for hit in fetched if hit.id in neighbour_ids]
+        heads = {hit.page_id: hit for hit in fetched if hit.id in head_ids}
+        return neighbours, heads
+
+    def _record_sources(self, hits: Iterable[_Hit], source_types: Dict[str, str]) -> None:
+        # Record structured citations (deduped by name+type) so the chat agent
+        # can surface them to the widget.
+        seen = {(s['name'], s['type']) for s in self.collected_sources}
+        for hit in hits:
+            key = (hit.name, source_types.get(hit.name, 'unknown'))
+            if key not in seen:
+                seen.add(key)
+                self.collected_sources.append({'name': key[0], 'type': key[1]})
+
+    def _render(
+        self, hits: Iterable[_Hit], heads: Dict[str, _Hit], source_types: Dict[str, str]
+    ) -> Tuple[str, List[_Hit]]:
+        """Group chunks by page, in page order, under one header per page.
+
+        Pages with matches are placed first and dropped whole once the result
+        would exceed the size cap — a page is never cut mid-chunk, and the cap
+        keeps one search from crowding out the rest of the conversation. Page
+        heads go in afterwards, only into pages that made it and only while
+        they still fit, so a head never displaces a page that matched.
+        Returns the text and the hits it contains."""
+        cap = settings.KNOWLEDGE_SEARCH_MAX_CHARS
+        pages: Dict[str, List[_Hit]] = {}
+        for hit in hits:
+            pages.setdefault(hit.page_id, []).append(hit)
+
+        placed: List[List[_Hit]] = []
+        total = 0
+        for page_hits in pages.values():
+            size = len(_page_block(page_hits, source_types)) + len(_PAGE_SEPARATOR)
+            if placed and total + size > cap:
+                break
+            placed.append(page_hits)
+            total += size
+
+        for page_hits in placed:
+            head = heads.get(page_hits[0].page_id)
+            if head is None:
+                continue
+            size = len(_chunk_text(head)) + len(_CHUNK_SEPARATOR)
+            if total + size <= cap:
+                page_hits.append(head)
+                total += size
+
+        blocks = [_page_block(page_hits, source_types) for page_hits in placed]
+        shown = [hit for page_hits in placed for hit in page_hits]
+        return _PAGE_SEPARATOR.join(blocks), shown
+
+
+_PAGE_SEPARATOR = "\n\n"
+_CHUNK_SEPARATOR = "\n"
+
+
+def _chunk_text(hit: _Hit) -> str:
+    label = f"(part {hit.chunk}/{hit.chunk_count}) " if hit.is_chunked else ""
+    return f"{label}{_hit_text(hit)}"
+
+
+def _page_block(page_hits: List[_Hit], source_types: Dict[str, str]) -> str:
+    """One page as the model sees it: a source header, then its chunks in
+    page order."""
+    page_hits.sort(key=lambda h: h.chunk or 0)
+    first = page_hits[0]
+    header = f"[{source_types.get(first.name, 'unknown').upper()} - {first.name}"
+    if first.url and first.url != first.name:
+        header += f" | {first.url}"
+    header += "]"
+    return header + " " + _CHUNK_SEPARATOR.join(_chunk_text(hit) for hit in page_hits)
+
+
+# A row this much bigger than a chunk was stored before pages were chunked and
+# has not been re-indexed yet (scripts/rechunk_knowledge.py). It is a data
+# defect, not knowledge to protect: one such row can be 100k+ chars.
+OVERSIZED_ROW_FACTOR = 4
+OVERSIZED_ROW_NOTE = "\n(page continues — not yet re-indexed in full)"
+
+
+def _hit_text(hit: _Hit) -> str:
+    limit = settings.KNOWLEDGE_CHUNK_SIZE * OVERSIZED_ROW_FACTOR
+    if len(hit.content) <= limit:
+        return hit.content
+    kept: List[str] = []
+    total = 0
+    for piece in split_text(hit.content, settings.KNOWLEDGE_CHUNK_SIZE):
+        if total + len(piece) > limit:
+            break
+        kept.append(piece)
+        total += len(piece)
+    return "".join(kept) + OVERSIZED_ROW_NOTE

backend/app/tools/mcp_connection.py

@@ -0,0 +1,115 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# An MCP tool's session, opened, held and closed by one task of its own.
+#
+# The MCP transports run inside anyio cancel scopes that belong to the task that
+# enters them. Entered from the request's own task, a refused streamable-HTTP
+# connect surfaced as a CancelledError instead of the error, and the leaked
+# scope cancelled the next connector in the same request too; closing from
+# another task failed with "exit cancel scope in a different task". The owner
+# task here enters and exits the tool's context itself, so a failure stays in it.
+
+import asyncio
+from typing import Optional
+
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+CONNECTION_FAILED = "Could not connect to the server (refused, unreachable or not an MCP endpoint)"
+
+# Strong references to owner tasks being torn down; without them the loop can
+# garbage collect a task mid-flight.
+_closing: set = set()
+
+
+def _forget_outcome(task: asyncio.Task) -> None:
+    """Read a finished owner task's exception so asyncio doesn't log it as never
+    retrieved; whoever cared has already reported it."""
+    if not task.cancelled():
+        task.exception()
+
+
+class HeldConnection:
+    def __init__(self, tool):
+        self.tool = tool
+        self._opened = asyncio.Event()
+        self._release = asyncio.Event()
+        self._task: Optional[asyncio.Task] = None
+
+    async def open(self, timeout: float) -> None:
+        """Connect within ``timeout`` seconds. Raises TimeoutError, or what the
+        connect raised (ConnectionError when the transport only cancelled)."""
+        self._task = asyncio.create_task(self._hold())
+        self._task.add_done_callback(_forget_outcome)
+        opened = asyncio.create_task(self._opened.wait())
+        try:
+            await asyncio.wait({opened, self._task}, timeout=timeout,
+                               return_when=asyncio.FIRST_COMPLETED)
+        except asyncio.CancelledError:
+            self._abandon()  # the request itself was cancelled
+            raise
+        finally:
+            opened.cancel()
+        if self._opened.is_set():
+            return
+        if not self._task.done():
+            self._abandon()
+            raise asyncio.TimeoutError()
+        if self._task.cancelled():
+            raise ConnectionError(CONNECTION_FAILED)
+        raise self._task.exception()
+
+    async def _hold(self) -> None:
+        await self.tool.__aenter__()
+        try:
+            self._opened.set()
+            await self._release.wait()
+        finally:
+            await self.tool.__aexit__(None, None, None)
+
+    def _abandon(self) -> None:
+        """Stop the owner without waiting: a STDIO server that never answered
+        can leave its unwind blocked until the child process exits."""
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            _closing.add(self._task)
+            self._task.add_done_callback(_closing.discard)
+
+    async def close(self, timeout: float) -> None:
+        """Ask the owner task to exit the tool's context, waiting up to
+        ``timeout`` seconds before abandoning it. Never raises."""
+        if self._task is None or self._task.done():
+            return
+        self._release.set()
+        try:
+            await asyncio.wait_for(asyncio.shield(self._task), timeout=timeout)
+        except asyncio.TimeoutError:
+            logger.debug("MCP tool did not close in time; abandoning it")
+            self._abandon()
+        except asyncio.CancelledError:
+            current = asyncio.current_task()
+            if current is not None and current.cancelling():
+                self._abandon()  # the caller itself is being cancelled
+                raise
+            # Otherwise the owner ended cancelled by its transport: it is closed.
+        except Exception as e:
+            logger.debug(f"MCP tool close raised (non-critical): {e}")
+
+    def release(self) -> None:
+        """Close without waiting."""
+        self._release.set()

backend/app/tools/mcp_manager.py

@@ -0,0 +1,555 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import asyncio
+from datetime import timedelta
+from time import monotonic
+from typing import List, Optional
+from agno.tools.mcp import MCPTools
+from app.channels.interactive_limits import InteractiveLimits
+from app.database import SessionLocal
+from app.repositories.mcp_tool import MCPToolRepository
+from app.models.mcp_tool import MCPTransportType
+from app.models.schemas.mcp_tool import MAX_USAGE_GUIDANCE_CHARS
+from app.core.logger import get_logger
+from app.core.outbound_policy import check_outbound_target
+from app.tools.mcp_connection import HeldConnection
+from app.tools.mcp_outbound import remote_params_classes
+from app.core.config import settings
+
+logger = get_logger(__name__)
+
+# Per-request read timeout for the MCP client session when a tool doesn't
+# configure one. It governs the startup handshake and every later tool call,
+# so it has to cover a cold `npx` launch (registry resolution + download) as
+# well as a slow query. agno's own default is 5s, which npx-launched servers
+# routinely exceed — hence the intermittent handshake failures this replaces.
+DEFAULT_TIMEOUT_SECONDS = 30
+
+# Headroom for process spawn on top of the requests the handshake itself
+# makes, so the outer guard never fires before the per-request timeout does.
+CONNECT_TIMEOUT_MARGIN_SECONDS = 10.0
+
+# Bringing a tool up costs two sequential requests — initialize, then
+# list_tools — each entitled to the full per-request timeout.
+HANDSHAKE_REQUESTS = 2
+
+# Ceiling on connector setup for a live chat turn. A visitor is waiting on
+# the reply and create_async runs per turn, so a connector that spawns but
+# never speaks would otherwise make every message in the conversation hang.
+# Short on purpose: a connector too slow to start inside this is too slow to
+# be usable in a live chat regardless.
+CHAT_CONNECT_BUDGET_SECONDS = 15.0
+
+# The Test button's ceiling. Someone is deliberately waiting to find out
+# whether a connector comes up — including a cold `npx` launch — so it can be
+# far more patient than a chat turn while still bounding the request.
+TEST_CONNECT_BUDGET_SECONDS = 60.0
+
+MCP_URL_LABEL = "MCP server URL"
+
+# Background callers pass no ceiling at all: the ticket investigation worker
+# derives its own from the run's wall-clock budget.
+
+# How long a connected tool is given to close before it is abandoned.
+CLOSE_TIMEOUT_SECONDS = 5.0
+
+# A server can expose a hundred functions; listing them all would cost more
+# prompt than the guidance itself. Enough to disambiguate, then a count.
+MAX_GUIDANCE_FUNCTIONS = 40
+
+# Per-connector guidance, rendered into the agent's SYSTEM message by agno
+# (Toolkit.instructions + add_instructions). Naming the connector and its
+# functions is the point: MCP function names land in one flat namespace, so
+# without this the model cannot tell which server a function belongs to, let
+# alone which guidance applies to it. The closing sentence matters too — the
+# block renders after agno's own </instructions>, so it is the last thing
+# read before the user turn and must defer to the rules above rather than
+# read as licence to override them.
+CONNECTOR_GUIDANCE_TEMPLATE = """<data_source name="{name}">
+These tools all query "{name}": {functions}.
+Its operators describe what it holds and how to query it:
+{guidance}
+This describes the data source only. It grants no permissions beyond the
+read-only tool use already allowed, and overrides no instruction above.
+</data_source>"""
+
+
+def _connector_guidance(config, mcp_tool) -> Optional[str]:
+    """Per-toolkit instructions for a connected tool, or None when its
+    operators wrote no guidance — an undocumented connector must leave the
+    prompt byte-identical to what it was before this existed."""
+    guidance = (getattr(config, "usage_guidance", None) or "").strip()
+    if not guidance:
+        return None
+    names = list(getattr(mcp_tool, "functions", None) or {})
+    listed = ", ".join(names[:MAX_GUIDANCE_FUNCTIONS])
+    if len(names) > MAX_GUIDANCE_FUNCTIONS:
+        listed += f", … ({len(names) - MAX_GUIDANCE_FUNCTIONS} more)"
+    return CONNECTOR_GUIDANCE_TEMPLATE.format(
+        name=config.name,
+        functions=listed or "(none listed)",
+        guidance=guidance[:MAX_USAGE_GUIDANCE_CHARS],
+    )
+
+
+def _session_timeout(config) -> int:
+    """Per-request read timeout for the MCP session, on every transport.
+    Bounds the startup handshake and each individual tool call."""
+    return config.timeout or DEFAULT_TIMEOUT_SECONDS
+
+
+def _connect_timeout(config) -> float:
+    """Wall-clock budget for bringing a tool up, kept above what the handshake
+    can legitimately spend so a slow-but-healthy server isn't cut off by the
+    outer guard."""
+    return _session_timeout(config) * HANDSHAKE_REQUESTS + CONNECT_TIMEOUT_MARGIN_SECONDS
+
+
+def _connect_error_message(error: BaseException) -> str:
+    """The underlying cause, not "unhandled errors in a TaskGroup": the MCP
+    transports wrap connection errors in exception groups."""
+    while isinstance(error, BaseExceptionGroup) and error.exceptions:
+        error = error.exceptions[0]
+    return str(error) or type(error).__name__
+
+
+class MCPToolsManager:
+    """Manager class for handling MCP tools initialization and cleanup"""
+
+    def __init__(self, connect_budget: Optional[float] = None):
+        """connect_budget caps the total time spent connecting this manager's
+        tools. Interactive callers pass one so a hanging connector can't stall
+        a reply; background callers leave it None and let each tool have its
+        configured budget."""
+        self.connect_budget = connect_budget
+        self.mcp_tools: List[MCPTools] = []
+        # Names of tools that connected, and {name, error} for those that
+        # didn't. Unlike mcp_tools (cleared on cleanup) these survive the run,
+        # so callers can report "loaded N of M" afterwards.
+        self.connected_tool_names: List[str] = []
+        self.failed_tools: List[dict] = []
+
+    async def initialize_mcp_tools_by_ids(
+        self, org_id: str, tool_ids: List[int]
+    ) -> List[MCPTools]:
+        """
+        Initialize a specific set of the organization's MCP tools by id —
+        used by the ticket investigation worker, whose connector selection
+        (organization_ticket_settings.investigation_mcp_tool_ids) is
+        deliberately separate from the chat-facing agent associations.
+        """
+        if not org_id or not tool_ids:
+            return []
+        try:
+            with SessionLocal() as db:
+                configs = MCPToolRepository(db).get_by_ids(org_id, tool_ids)
+        except Exception as e:
+            logger.error(f"Failed to load MCP tools {tool_ids} for org {org_id}: {e}")
+            return []
+        found_ids = {config.id for config in configs}
+        for missing_id in tool_ids:
+            if missing_id not in found_ids:
+                self.failed_tools.append({
+                    "name": f"Tool #{missing_id}",
+                    "error": "Configured tool no longer exists or is disabled",
+                })
+        return await self._initialize_from_configs(configs)
+
+    async def initialize_mcp_tools(self, agent_id: str, org_id: str) -> List[MCPTools]:
+        """
+        Initialize MCP tools for an agent asynchronously.
+        Returns a list of connected MCPTools instances.
+        """
+        if not agent_id or not org_id:
+            return []
+
+        try:
+            # Get MCP tools for this agent from database
+            with SessionLocal() as db:
+                mcp_tool_repo = MCPToolRepository(db)
+                agent_mcp_tools = mcp_tool_repo.get_agent_mcp_tools(agent_id)
+        except Exception as e:
+            logger.error(f"Failed to get MCP tools for agent {agent_id}: {e}")
+            return self.mcp_tools
+        return await self._initialize_from_configs(agent_mcp_tools)
+
+    async def _initialize_from_configs(self, configs) -> List[MCPTools]:
+        """Build + connect each configured tool, keeping only the ones that
+        come up with functions available."""
+        deadline = self._deadline()
+        try:
+            # Initialize each MCP tool asynchronously
+            for mcp_tool_config in configs:
+                try:
+                    connect_timeout = self._budgeted_connect_timeout(mcp_tool_config, deadline)
+                    if connect_timeout <= 0:
+                        # Earlier connectors ate the budget. Say so rather than
+                        # reporting this one as a connection failure.
+                        logger.warning(f"Skipping MCP tool {mcp_tool_config.name}: connect budget exhausted")
+                        self.failed_tools.append({
+                            "name": mcp_tool_config.name,
+                            "error": "Skipped — the earlier connectors used up the time available",
+                        })
+                        continue
+                    logger.debug(f"Initializing MCP tool: {mcp_tool_config.name}")
+                    mcp_tool = self._build_tool(mcp_tool_config)
+                    await self._connect_and_register(
+                        mcp_tool, mcp_tool_config.name, connect_timeout,
+                        config=mcp_tool_config,
+                    )
+                except Exception as e:
+                    logger.error(f"Failed to initialize MCP tool {mcp_tool_config.name}: {e}")
+                    import traceback
+                    logger.error(f"MCP tool error traceback: {traceback.format_exc()}")
+                    self.failed_tools.append({"name": mcp_tool_config.name, "error": str(e)})
+                    continue
+
+        except Exception as e:
+            logger.error(f"Failed to initialize MCP tools: {e}")
+
+        logger.debug(f"Initialized {len(self.mcp_tools)} MCP tools")
+        return self.mcp_tools
+
+    def _deadline(self) -> Optional[float]:
+        """When this manager's overall connect budget runs out, or None when
+        it doesn't have one."""
+        if self.connect_budget is None:
+            return None
+        return monotonic() + self.connect_budget
+
+    def _budgeted_connect_timeout(self, config, deadline: Optional[float]) -> float:
+        """The tool's own connect budget, trimmed to whatever is left of the
+        manager's overall one."""
+        connect_timeout = _connect_timeout(config)
+        if deadline is None:
+            return connect_timeout
+        return min(connect_timeout, deadline - monotonic())
+
+    @classmethod
+    def _build_tool(cls, config) -> Optional[MCPTools]:
+        """MCPTools for a config of any transport, or None (with a logged
+        reason) when the config is unusable."""
+        if config.transport_type == MCPTransportType.STDIO:
+            return cls._build_stdio_tool(config)
+        if config.transport_type in (MCPTransportType.SSE, MCPTransportType.HTTP):
+            return cls._build_remote_tool(config)
+        logger.warning(f"MCP tool {config.name} has unsupported transport {config.transport_type}, skipping")
+        return None
+
+    @staticmethod
+    def _build_stdio_tool(config) -> Optional[MCPTools]:
+        """MCPTools for a local subprocess server (npx/uvx/binary)."""
+        if not settings.MCP_STDIO_ENABLED:
+            # Connectors saved before it was turned off never get to run.
+            logger.warning(f"STDIO MCP tool {config.name} skipped: MCP_STDIO_ENABLED is false")
+            return None
+        if not (config.command and config.args):
+            logger.warning(f"STDIO MCP tool {config.name} missing command or args")
+            return None
+
+        command_parts = [config.command] + config.args
+
+        # The filesystem server takes its allowed directories as trailing
+        # arguments; accept them from ALLOWED_DIRECTORIES too.
+        if "@modelcontextprotocol/server-filesystem" in str(config.args):
+            args_after_package = []
+            package_found = False
+            for arg in config.args:
+                if package_found:
+                    args_after_package.append(arg)
+                elif arg == "@modelcontextprotocol/server-filesystem":
+                    package_found = True
+
+            if not args_after_package:
+                allowed_dirs_env = (config.env_vars or {}).get("ALLOWED_DIRECTORIES")
+                directories = [d.strip() for d in (allowed_dirs_env or "").split(",") if d.strip()]
+                if not directories:
+                    logger.warning(f"Filesystem MCP tool {config.name} missing directory arguments (args or ALLOWED_DIRECTORIES), skipping")
+                    return None
+                command_parts.extend(directories)
+                logger.debug(f"Added directories from env_vars: {directories}")
+
+        command_str = " ".join(command_parts)
+        logger.debug(f"Creating STDIO MCP tool with command: {command_str}")
+
+        # Prepare environment variables if provided (excluding ALLOWED_DIRECTORIES which we handled above)
+        env_vars_for_process = None
+        if config.env_vars:
+            env_vars_for_process = {k: v for k, v in config.env_vars.items() if k != "ALLOWED_DIRECTORIES"}
+            if env_vars_for_process:
+                # Values may hold credentials (API keys, tokens) — log names only
+                logger.debug(f"Environment variables configured: {list(env_vars_for_process.keys())}")
+
+        return MCPTools(
+            command_str,
+            env=env_vars_for_process,
+            timeout_seconds=_session_timeout(config),
+        )
+
+    async def test_tool_config(self, config) -> dict:
+        """Connect to a configured tool once and report what happened — backs
+        the Test button on the MCP config page. Goes through the same
+        build/connect path as a real run, so the reported error is exactly
+        what a run would record. Never raises."""
+        failures_before = len(self.failed_tools)
+        deadline = self._deadline()
+        try:
+            mcp_tool = self._build_tool(config)
+            connected = await self._connect_and_register(
+                mcp_tool, config.name, self._budgeted_connect_timeout(config, deadline)
+            )
+        except Exception as e:
+            return {"success": False, "functions": [], "error": str(e)}
+        if connected:
+            functions = list(getattr(mcp_tool, "functions", None) or {})
+            await self.cleanup_mcp_tools()
+            return {"success": True, "functions": functions, "error": None}
+        new_failures = self.failed_tools[failures_before:]
+        error = new_failures[-1]["error"] if new_failures else "Failed to connect to the server"
+        return {"success": False, "functions": [], "error": error}
+
+    @staticmethod
+    def _build_remote_tool(config) -> Optional[MCPTools]:
+        """MCPTools for a remote MCP server. HTTP uses the streamable-HTTP
+        transport; SSE is kept for servers that only speak the older
+        transport."""
+        if not config.url:
+            logger.warning(f"Remote MCP tool {config.name} missing URL, skipping")
+            return None
+        # Checked again at connect time, not only on save: DNS can change.
+        check_outbound_target(config.url, MCP_URL_LABEL)
+        # Under public_only these also pin every connect to a vetted address.
+        sse_params_cls, http_params_cls = remote_params_classes()
+        headers = config.headers or None
+        timeout = _session_timeout(config)
+        sse_read_timeout = config.sse_read_timeout or 300
+        if config.transport_type == MCPTransportType.SSE:
+            server_params = sse_params_cls(
+                url=config.url,
+                headers=headers,
+                timeout=timeout,
+                sse_read_timeout=sse_read_timeout,
+            )
+            return MCPTools(
+                url=config.url,
+                transport="sse",
+                server_params=server_params,
+                timeout_seconds=timeout,
+            )
+        server_params = http_params_cls(
+            url=config.url,
+            headers=headers,
+            timeout=timedelta(seconds=timeout),
+            sse_read_timeout=timedelta(seconds=sse_read_timeout),
+            terminate_on_close=(
+                config.terminate_on_close if config.terminate_on_close is not None else True
+            ),
+        )
+        return MCPTools(
+            url=config.url,
+            transport="streamable-http",
+            server_params=server_params,
+            timeout_seconds=timeout,
+        )
+
+    async def _connect_and_register(
+        self, mcp_tool: Optional[MCPTools], name: str, connect_timeout: float,
+        config=None,
+    ) -> bool:
+        """Connect a built tool, verify it exposes functions, and register it
+        for use + cleanup. Failed tools are torn down, never registered."""
+        if mcp_tool is None:
+            self.failed_tools.append({
+                "name": name,
+                "error": "Tool is misconfigured — check its command/args (STDIO) or URL (SSE/HTTP)",
+            })
+            return False
+        connection = HeldConnection(mcp_tool)
+        try:
+            await connection.open(connect_timeout)
+            logger.debug(f"Entered MCP tool context: {name}")
+        except asyncio.TimeoutError:
+            logger.error(f"Timeout connecting to MCP tool {name}")
+            self.failed_tools.append({
+                "name": name,
+                "error": f"Timed out after {connect_timeout:.0f}s connecting to the server",
+            })
+            return False
+        except Exception as e:
+            error = _connect_error_message(e)
+            logger.error(f"Failed to connect MCP tool {name}: {error}")
+            # For package not found errors (like Git server), skip silently after first error
+            if "404" in error or "not found" in error.lower() or "no such package" in error.lower():
+                logger.warning(f"MCP tool package not found, skipping: {name}")
+            self.failed_tools.append({"name": name, "error": error})
+            return False
+        mcp_tool._held_connection = connection
+
+        # Verify functions are loaded after connection
+        if getattr(mcp_tool, "functions", None):
+            logger.debug(f"MCP tool {name} loaded functions: {list(mcp_tool.functions.keys())}")
+            self._prepare_functions_for_provider(mcp_tool, name)
+            # Configured display name — lets consumers (e.g. the investigation
+            # evidence log) attribute each tool call to its connector.
+            mcp_tool._connector_name = name
+            # agno Toolkit hook: collected in Agent._add_tool and rendered
+            # into the SYSTEM message. Set only after a successful connect, so
+            # guidance never describes a source that isn't actually there.
+            if config is not None:
+                guidance = _connector_guidance(config, mcp_tool)
+                if guidance:
+                    mcp_tool.instructions = guidance
+                    mcp_tool.add_instructions = True
+            self.mcp_tools.append(mcp_tool)
+            self.connected_tool_names.append(name)
+            return True
+        logger.warning(f"MCP tool {name} has no functions available after connection")
+        self.failed_tools.append({"name": name, "error": "Connected, but the server exposed no tools"})
+        connection.release()
+        return False
+
+    @staticmethod
+    def _prepare_functions_for_provider(mcp_tool: MCPTools, name: str) -> None:
+        """Keep a connected server's tools out of the provider's strict mode.
+
+        Whenever an agent has a response_model, agno marks every tool `strict`
+        — including these, whose schemas come from third-party servers. A
+        foreign schema generally can't satisfy OpenAI's strict subset: an
+        open-ended record (zod's `z.record`, which the Elasticsearch server
+        uses for `queryBody`) has no strict equivalent at all, and agno's
+        strict shim only stamps `additionalProperties` on the top level, so
+        any nested object is refused as well. One such tool then 400s every
+        request that carries it, which empties an investigation of evidence
+        and breaks chat outright (#303).
+
+        Strict is what we want for OUR structured output, not for schemas we
+        don't control. agno only defaults this when it is still None, so
+        setting it here is enough to keep it off.
+        """
+        for function in (getattr(mcp_tool, "functions", None) or {}).values():
+            function.strict = False
+        logger.debug(f"MCP tool {name} functions opted out of provider strict mode")
+
+    async def cleanup_mcp_tools(self):
+        """Close every connected tool, each from the task that opened it."""
+        for mcp_tool in self.mcp_tools:
+            connection = getattr(mcp_tool, "_held_connection", None)
+            if connection is not None:
+                await connection.close(timeout=CLOSE_TIMEOUT_SECONDS)
+        self.mcp_tools.clear()
+        logger.debug("All MCP tools cleaned up")
+
+
+# Convenience functions for backward compatibility and easy usage
+async def initialize_mcp_tools(agent_id: str, org_id: str) -> List[MCPTools]:
+    """
+    Initialize MCP tools for an agent asynchronously.
+    Returns a list of connected MCPTools instances.
+    """
+    manager = MCPToolsManager()
+    return await manager.initialize_mcp_tools(agent_id, org_id)
+
+
+async def cleanup_mcp_tools(mcp_tools: List[MCPTools]):
+    """
+    Clean up a list of MCP tools.
+    """
+    manager = MCPToolsManager()
+    manager.mcp_tools = mcp_tools
+    await manager.cleanup_mcp_tools()
+
+
+class ChatAgentMCPMixin:
+    """
+    Mixin class to add MCP tools functionality to ChatAgent
+    """
+    
+    @classmethod
+    async def create_async(cls, api_key: str, model_name: str = "gpt-4o-mini", model_type: str = "OPENAI",
+                          org_id: str = None, agent_id: str = None, customer_id: str = None,
+                          session_id: str = None, custom_system_prompt: str = None,
+                          transfer_to_human: bool | None = None, source: str = None,
+                          channel: str = None, extra_context: str = None, base_url: str = None,
+                          choice_limits: Optional[InteractiveLimits] = None):
+        """
+        Async factory method to create a ChatAgent with MCP tools initialized.
+        """
+        # Initialize MCP tools asynchronously if agent_id and org_id are provided
+        mcp_tools = []
+        mcp_manager = None
+        if agent_id and org_id:
+            try:
+                mcp_manager = MCPToolsManager(
+                    connect_budget=CHAT_CONNECT_BUDGET_SECONDS
+                )
+                mcp_tools = await mcp_manager.initialize_mcp_tools(agent_id, org_id)
+            except Exception as e:
+                logger.error(f"Failed to initialize MCP tools: {e}")
+
+        # Create ChatAgent instance with initialized MCP tools
+        instance = cls(
+            api_key=api_key,
+            model_name=model_name,
+            model_type=model_type,
+            org_id=org_id,
+            agent_id=agent_id,
+            customer_id=customer_id,
+            session_id=session_id,
+            custom_system_prompt=custom_system_prompt,
+            transfer_to_human=transfer_to_human,
+            mcp_tools=mcp_tools,
+            source=source,
+            channel=channel,
+            extra_context=extra_context,
+            base_url=base_url,
+            choice_limits=choice_limits,
+        )
+        
+        # Attach the MCP manager to the instance for cleanup
+        instance._mcp_manager = mcp_manager
+        
+        return instance
+    
+    async def cleanup_mcp_tools(self):
+        """
+        Clean up MCP tools by properly disconnecting them.
+        """
+        if hasattr(self, '_mcp_manager') and self._mcp_manager:
+            await self._mcp_manager.cleanup_mcp_tools()
+        elif hasattr(self, 'mcp_tools') and self.mcp_tools:
+            await cleanup_mcp_tools(self.mcp_tools)
+
+    async def safe_cleanup_mcp_tools(self, timeout: float = 2.0):
+        """
+        Best-effort MCP cleanup after a chat turn: bounded by a timeout and
+        never raises, so cleanup can't break or block the response flow.
+        """
+        try:
+            await asyncio.wait_for(self.cleanup_mcp_tools(), timeout=timeout)
+        except asyncio.TimeoutError:
+            logger.debug("MCP cleanup timed out (non-critical)")
+        except Exception as e:
+            logger.debug(f"MCP cleanup warning (non-critical): {e}")
+    
+    def __del__(self):
+        """
+        Destructor to clean up MCP tools if they weren't properly cleaned up.
+        Note: This is a fallback and shouldn't be relied upon for proper cleanup.
+        """
+        if hasattr(self, 'mcp_tools') and self.mcp_tools:
+            logger.debug("MCP tools cleanup detected in destructor (likely due to async context cleanup timing)")
+            # Can't run async code in __del__, so we just log for debugging 

backend/app/tools/mcp_outbound.py

@@ -0,0 +1,55 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+"""Remote MCP connection params that honour OUTBOUND_URL_POLICY at connect
+time. agno's MCPTools passes its params dataclass to the mcp SDK's
+sse_client / streamablehttp_client as keyword arguments, so adding an
+``httpx_client_factory`` field is how the SDK's httpx client (and the
+redirects it follows) gets the address guard."""
+
+from dataclasses import dataclass
+from typing import Callable, Tuple, Type
+
+from agno.tools.mcp import SSEClientParams, StreamableHTTPClientParams
+
+from app.core.outbound_http import guarded_async_http_client
+from app.core.outbound_policy import public_only
+
+
+def guarded_mcp_http_client(headers=None, timeout=None, auth=None):
+    """The mcp SDK's httpx_client_factory, dialling only vetted public
+    addresses. Redirects stay on, as in the SDK's default factory."""
+    return guarded_async_http_client(
+        headers=headers, timeout=timeout, auth=auth, follow_redirects=True
+    )
+
+
+@dataclass
+class PinnedSSEClientParams(SSEClientParams):
+    httpx_client_factory: Callable = guarded_mcp_http_client
+
+
+@dataclass
+class PinnedStreamableHTTPClientParams(StreamableHTTPClientParams):
+    httpx_client_factory: Callable = guarded_mcp_http_client
+
+
+def remote_params_classes() -> Tuple[Type[SSEClientParams], Type[StreamableHTTPClientParams]]:
+    """The (SSE, streamable-HTTP) params classes for the current policy;
+    agno's own, untouched, under "any"."""
+    if public_only():
+        return PinnedSSEClientParams, PinnedStreamableHTTPClientParams
+    return SSEClientParams, StreamableHTTPClientParams

backend/app/tools/shopify_order_access.py

@@ -0,0 +1,93 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+"""Who may see a Shopify order through the chat agent.
+
+Order numbers are sequential, so a number alone proves nothing. A shopper sees an
+order only when they also give the email it was placed with, and that email matches
+the order exactly. A wrong email and a missing order get the same answer, so the
+reply never confirms that an order number exists.
+"""
+
+import re
+from typing import Any, Dict, Optional
+
+# Same reply for "no such order" and "not your order": never confirm an order exists.
+ORDER_NOT_FOUND = (
+    "No order matches that order number and email address. "
+    "Ask the customer to check both against their order confirmation email."
+)
+EMAIL_REQUIRED = (
+    "Ask the customer for the email address they used at checkout. "
+    "Orders are only shared with the person who placed them."
+)
+ORDER_NUMBER_REQUIRED = "Ask the customer for their order number (for example #1001)."
+INVALID_ORDER_NUMBER = "That doesn't look like an order number. Ask the customer to check it."
+
+MAX_ORDER_RESULTS = 10
+
+# Restricted to characters that are inert in Shopify search syntax (no spaces,
+# quotes, colons, brackets or the * wildcard), so a value can't widen the query.
+_EMAIL = re.compile(r"^[A-Za-z0-9.!#$%&'+/=?^_`{|}~-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$")
+# Shopify order names can carry a custom prefix or suffix (e.g. "SHOP-1001-UK").
+_ORDER_NUMBER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9-]{0,31}$")
+
+
+def normalise_email(email: Optional[str]) -> str:
+    return (email or "").strip().lower()
+
+
+def normalise_order_number(order_number: Optional[str]) -> str:
+    return (order_number or "").strip().lstrip("#").strip().lower()
+
+
+def order_lookup_problem(customer_email: Optional[str], order_number: Optional[str],
+                         number_required: bool = False) -> Optional[str]:
+    """Why this lookup can't run, or None when it can."""
+    if not _EMAIL.match(normalise_email(customer_email)):
+        return EMAIL_REQUIRED
+    number = normalise_order_number(order_number)
+    if not number:
+        return ORDER_NUMBER_REQUIRED if number_required else None
+    if not _ORDER_NUMBER.match(number):
+        return INVALID_ORDER_NUMBER
+    return None
+
+
+def build_order_search(customer_email: str, order_number: Optional[str] = None) -> str:
+    """Shopify search syntax for one customer's orders. Inputs must already pass
+    order_lookup_problem, which limits them to characters inert in the syntax."""
+    terms = [f"email:{normalise_email(customer_email)}"]
+    number = normalise_order_number(order_number)
+    if number:
+        terms.append(f"name:{number}")
+    return " AND ".join(terms)
+
+
+def order_belongs_to(order: Dict[str, Any], customer_email: str) -> bool:
+    """True when the email given matches the order's own email or its customer's."""
+    wanted = normalise_email(customer_email)
+    customer = order.get("customer") or {}
+    return bool(wanted) and wanted in {
+        normalise_email(order.get("email")),
+        normalise_email(customer.get("email")),
+    }
+
+
+def order_number_matches(order: Dict[str, Any], order_number: Optional[str]) -> bool:
+    """Exact match on the order name, so #1005 never returns #10050."""
+    number = normalise_order_number(order_number)
+    return not number or normalise_order_number(order.get("name")) == number

backend/app/tools/ticket_toolkit.py

@@ -0,0 +1,265 @@
+"""
+Copyright 2024-2026 ChatterMate
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import json
+import re
+from typing import Optional
+from uuid import UUID
+
+from agno.tools import Toolkit
+
+from app.core.logger import get_logger
+from app.database import SessionLocal
+from app.models.session_to_agent import SessionToAgent
+from app.models.ticket import TicketPriority, TicketSource
+from app.repositories.customer import CustomerRepository
+from app.repositories.session_to_agent import SessionToAgentRepository
+from app.services.widget_identity import trusts_identity_in_conversation
+from app.models.ticket_activity import TicketActivityType, TicketActorType
+
+logger = get_logger(__name__)
+
+VALID_PRIORITIES = {p.value for p in TicketPriority}
+
+# Loose sanity check only — a real inbox is not verified here, we just refuse
+# to store obviously-not-an-email junk the model might pass.
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+def _clean_email(email: Optional[str]) -> Optional[str]:
+    if not email:
+        return None
+    email = email.strip().lower()
+    return email if _EMAIL_RE.match(email) else None
+
+
+def _clean_name(name: Optional[str]) -> Optional[str]:
+    name = (name or "").strip()
+    return name or None
+
+
+class TicketTools(Toolkit):
+    """Native ticket tools for the customer-facing chat agent — the AI-first
+    replacement for JiraTools. One native ticket per session: a second
+    create_ticket call appends the new details as an activity instead of
+    opening a duplicate.
+    """
+
+    def __init__(self, agent_id: str, org_id: str, session_id: str):
+        super().__init__(name="ticket_tools")
+        self.agent_id = agent_id
+        self.org_id = org_id
+        self.session_id = session_id
+
+        self.register(self.create_ticket)
+        self.register(self.get_ticket_status)
+        self.register(self.check_existing_ticket)
+
+    def create_ticket(
+        self,
+        summary: str,
+        description: str,
+        priority: Optional[str] = "medium",
+        customer_email: Optional[str] = None,
+        customer_name: Optional[str] = None,
+    ) -> str:
+        """
+        Create a support ticket for the current conversation, or add the new
+        details to the session's existing ticket. Use this when the customer
+        reports a technical issue you cannot resolve from the knowledge base —
+        the ticket is investigated by the support team's AI and humans.
+
+        Always pass the customer's account email and registered name when you
+        know them (ask the customer first if they haven't been shared) — the
+        support AI uses them to look the customer up in the connected systems,
+        and without a real email it cannot analyse the customer's own records.
+
+        Args:
+            summary (str): Short title of the issue.
+            description (str): Detailed description: what happens, error
+                messages, customer impact, and anything needed to reproduce.
+            priority (str, optional): urgent, high, medium or low. Defaults to
+                "medium".
+            customer_email (str, optional): The customer's account email, as
+                they gave it. Used to correlate them in the support systems.
+            customer_name (str, optional): The customer's registered name.
+
+        Returns:
+            str: JSON string with the ticket number and status.
+        """
+        try:
+            from app.services.ticket import TicketService
+
+            priority_value = (priority or "medium").lower()
+            if priority_value not in VALID_PRIORITIES:
+                priority_value = TicketPriority.MEDIUM.value
+
+            email = _clean_email(customer_email)
+            name = _clean_name(customer_name)
+
+            with SessionLocal() as db:
+                service = TicketService(db)
+                session_uuid = UUID(str(self.session_id))
+                conversation = SessionToAgentRepository(db).get_session(session_uuid)
+                customer = (
+                    CustomerRepository(db).get_by_id(conversation.customer_id)
+                    if conversation is not None and conversation.customer_id else None
+                )
+                trusted = trusts_identity_in_conversation(db, customer, conversation)
+                if trusted:
+                    # Enrich the (usually anonymous) widget customer with the
+                    # identity the customer stated in chat, so the ticket — and
+                    # the investigator's DB correlation — carry a real email +
+                    # name instead of the …@noemail.com placeholder.
+                    self._capture_customer_identity(db, conversation, email, name)
+                else:
+                    # A visitor who only typed a customer's email is not them:
+                    # the ticket carries no customer, so the investigator has no
+                    # one's records to look up or quote back into this chat.
+                    email = name = None
+                existing = service.repo.get_by_session(session_uuid)
+                if existing is not None:
+                    service._add_activity(
+                        existing,
+                        TicketActivityType.CUSTOMER_REPLIED,
+                        actor_type=TicketActorType.AI,
+                        body=f"Additional details from the conversation:\n{description}",
+                    )
+                    db.commit()
+                    return json.dumps({
+                        "success": True,
+                        "updated": True,
+                        "ticket_id": existing.display_number,
+                        "status": str(existing.status),
+                        "message": (
+                            f"Ticket {existing.display_number} already exists for this "
+                            "conversation — the new details were added to it."
+                        ),
+                    })
+
+                ticket, _duplicates = service.create_ticket(
+                    organization_id=UUID(str(self.org_id)),
+                    title=summary[:500],
+                    description=description,
+                    priority=priority_value,
+                    source=TicketSource.CHAT_AI,
+                    session_id=session_uuid,
+                    agent_id=UUID(str(self.agent_id)),
+                    customer_email=email,
+                    customer_name=name,
+                    link_session_customer=trusted,
+                )
+                db.commit()
+                db.refresh(ticket)
+                ticket_number = ticket.display_number
+                status = str(ticket.status)
+
+            # The acknowledgment message is sent by the chat agent itself in
+            # its reply, so no separate customer notification here.
+            return json.dumps({
+                "success": True,
+                "updated": False,
+                "ticket_id": ticket_number,
+                "status": status,
+                "message": f"Ticket {ticket_number} created. The team's AI will start investigating.",
+            })
+        except Exception as e:
+            logger.error(f"create_ticket failed for session {self.session_id}: {e}")
+            return json.dumps({"success": False, "message": "Failed to create the ticket."})
+
+    def _capture_customer_identity(
+        self, db, conversation: SessionToAgent, email: Optional[str], name: Optional[str]
+    ) -> None:
+        """Fold a stated email/name onto the conversation's customer record in place.
+
+        Widget visitors are anonymous (`…@noemail.com`, no name); the customer
+        naming their real account in chat is the only identity the investigator
+        gets. update_contact only overwrites a placeholder email and never
+        clobbers a real one or a channel identity key. Only for a conversation
+        trusted to speak for its customer (see create_ticket).
+        """
+        if not email and not name:
+            return
+        try:
+            CustomerRepository(db).update_contact(
+                conversation.customer_id, email=email, full_name=name
+            )
+            db.commit()
+        except Exception as e:
+            db.rollback()
+            logger.error(
+                f"Failed to capture customer identity for session {conversation.session_id}: {e}"
+            )
+
+    def get_ticket_status(self, ticket_number: Optional[str] = None) -> str:
+        """
+        Get the current status of a ticket. Without a ticket number, returns
+        the status of this conversation's ticket.
+
+        Args:
+            ticket_number (str, optional): Ticket number like "TKT-123".
+
+        Returns:
+            str: JSON string with the ticket status and priority.
+        """
+        try:
+            from app.repositories.ticket import TicketRepository
+
+            with SessionLocal() as db:
+                repo = TicketRepository(db)
+                ticket = None
+                if ticket_number:
+                    digits = str(ticket_number).strip().upper().removeprefix("TKT-")
+                    if digits.isdigit():
+                        ticket = repo.get_by_number(UUID(str(self.org_id)), int(digits))
+                else:
+                    ticket = repo.get_by_session(UUID(str(self.session_id)))
+                if ticket is None or str(ticket.organization_id) != str(self.org_id):
+                    return json.dumps({"exists": False, "message": "No ticket found."})
+                return json.dumps({
+                    "exists": True,
+                    "ticket_id": ticket.display_number,
+                    "status": str(ticket.status),
+                    "priority": str(ticket.priority),
+                    "title": ticket.title,
+                })
+        except Exception as e:
+            logger.error(f"get_ticket_status failed: {e}")
+            return json.dumps({"exists": False, "message": "Could not look up the ticket."})
+
+    def check_existing_ticket(self) -> str:
+        """
+        Check whether this conversation already has a ticket. Always call this
+        before creating a ticket.
+
+        Returns:
+            str: JSON string with "exists" and the ticket number if present.
+        """
+        try:
+            from app.repositories.ticket import TicketRepository
+
+            with SessionLocal() as db:
+                ticket = TicketRepository(db).get_by_session(UUID(str(self.session_id)))
+                if ticket is None:
+                    return json.dumps({"exists": False})
+                return json.dumps({
+                    "exists": True,
+                    "ticket_id": ticket.display_number,
+                    "status": str(ticket.status),
+                })
+        except Exception as e:
+            logger.error(f"check_existing_ticket failed: {e}")
+            return json.dumps({"exists": False})