centive-sdk 2.2.0.dev8__tar.gz → 2.2.0.dev9__tar.gz

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are documented in this file.
 
+## Unreleased
+
+### Added
+
+- **Grounded knowledge search for Aria's client tool.** A new websocket frame,
+  `type: "kb_search"` (`request_id`, `query`, optional `alternate_query`,
+  `user_messages`), is forwarded to Centive's `POST /anam/kb-search`, which
+  searches only this organization's knowledge folders with several phrasings
+  and returns an evidence packet. The server answers with
+  `type: "kb_search_response"` carrying the same `request_id` and either
+  `status: "success", packet` or `status: "error", error` (`INVALID_KB_SEARCH`,
+  `KB_SEARCH_UNAVAILABLE`). In token mode the frame is bound to the connection's
+  user like every other frame. A failed lookup is reported, never guessed.
+- `AsyncSessions.kb_search(KbSearchRequest) -> KbSearchResponse` and
+  `ClientConfig.kb_search_path` (default `/anam/kb-search`).
+- The `kb_search` frame's `session_id` and `user_id` are forwarded to Centive as
+  `session_id` / `external_user_id` on `KbSearchRequest`, so a question the
+  documentation could not answer is logged against the conversation in the
+  organization's knowledge-gap log.
+- The browser's declared `capabilities` (e.g. `["kb_search"]`) on the `user_trigger`
+  frame are validated, remembered for the connection and forwarded on every
+  trigger-session call as `TriggerSessionRequest.capabilities`, so Centive attaches
+  Aria's client search tool only to sessions whose frontend can serve it.
+
+### Changed
+
+- `AsyncSessions.kb_search` makes a single attempt (no retries). Centive spends up to
+  8 s searching, the browser stops waiting at 12 s and Anam's tool times out at 15 s,
+  so a retried 503 could only arrive after everyone had given up. `_make_request`
+  accepts a per-call `max_retries` for this.
+
 ## v2.2.0
 
 Unreleased (branch `feature/user-page-tracking`, merged with the v2.1.0

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.2.0.dev8
+Version: 2.2.0.dev9
 Summary: Python SDK for Centive backend integration
 Project-URL: Homepage, https://github.com/TheAgenticAI/centive-backend-sdk
 Project-URL: Repository, https://github.com/TheAgenticAI/centive-backend-sdk

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "centive-sdk"
-version = "2.2.0.dev8"
+version = "2.2.0.dev9"
 description = "Python SDK for Centive backend integration"
 readme = "README.md"
 license = "MIT"

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/config.py

@@ -39,6 +39,7 @@ class ClientConfig(BaseModel):
     save_messages_path: str = "/anam/save-messages"
     pause_status_path: str = "/anam/pause-status"
     events_path: str = "/anam/events"
+    kb_search_path: str = "/anam/kb-search"
     timeout_seconds: float = 10.0
     max_retries: int = 3
     initial_retry_delay: float = 0.5

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/models/__init__.py

@@ -1,4 +1,6 @@
 from .requests import (
+    KbSearchFrame,
+    KbSearchRequest,
     ProductEventBatchRequest,
     TelemetryEvent,
     TelemetryFrame,
@@ -7,6 +9,7 @@ from .requests import (
     TriggerSessionRequest,
 )
 from .responses import (
+    KbSearchResponse,
     PauseStatusResponse,
     ProductEventIngestResponse,
     ToolMappingResponse,
@@ -14,6 +17,9 @@ from .responses import (
 )
 
 __all__ = [
+    "KbSearchRequest",
+    "KbSearchFrame",
+    "KbSearchResponse",
     "ToolMappingRequest",
     "TriggerSessionRequest",
     "TelemetryEvent",

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/models/requests.py

@@ -1,3 +1,4 @@
+import re
 from typing import Any, Dict, List, Literal, Optional
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
@@ -28,6 +29,23 @@ class TriggerSessionRequest(BaseModel):
     current_page: Optional["TelemetryPage"] = Field(
         None, description="page the browser reports having open when it asks for a session"
     )
+    # What the browser SDK can serve in this session ("kb_search" for Aria's awaited
+    # knowledge-search tool). Centive attaches that tool only to sessions that
+    # declare it, so a customer on an older frontend never gets a tool nobody
+    # answers. Omitted when the browser declared nothing.
+    capabilities: Optional[List[str]] = Field(
+        None, max_length=16, description="capabilities the browser SDK declared for this session"
+    )
+
+    @field_validator("capabilities")
+    @classmethod
+    def _capability_tokens(cls, capabilities: Optional[List[str]]) -> Optional[List[str]]:
+        if capabilities is None:
+            return None
+        for capability in capabilities:
+            if not re.fullmatch(r"[a-z0-9_]{1,32}", capability):
+                raise ValueError("capabilities must be lowercase tokens of at most 32 characters")
+        return list(dict.fromkeys(capabilities))
 
 
 class SessionMessage(BaseModel):
@@ -96,6 +114,33 @@ class SessionEndEvent(BaseModel):
     user_id: str = Field(..., description="user ID")
 
 
+class KbSearchRequest(BaseModel):
+    """request payload for POST /anam/kb-search: grounded evidence for Aria's client search tool."""
+
+    query: str = Field(..., min_length=1, max_length=4000, description="the user's sentence or the model's query")
+    alternate_query: Optional[str] = Field(None, max_length=4000, description="optional second phrasing")
+    user_messages: List[str] = Field(default_factory=list, max_length=10, description="the user's turns so far")
+    session_id: Optional[str] = Field(None, max_length=255, description="Anam session id, so unanswered questions tie to the conversation")
+    external_user_id: Optional[str] = Field(None, max_length=255, description="end-user id, for the knowledge-gap log")
+
+    @field_validator("user_messages")
+    @classmethod
+    def _bounded_user_messages(cls, messages: List[str]) -> List[str]:
+        for message in messages:
+            if len(message) > 4000:
+                raise ValueError("user message longer than 4000 characters")
+        return messages
+
+
+class KbSearchFrame(KbSearchRequest):
+    """kb_search frame from FE SDK; answered with a kb_search_response frame carrying request_id."""
+
+    type: Literal["kb_search"] = "kb_search"
+    request_id: str = Field(..., min_length=1, max_length=128, description="client-chosen id echoed in the response")
+    session_id: Optional[str] = Field(None, description="Anam session id when known")
+    user_id: Optional[str] = Field(None, description="user id (checked against the connection identity)")
+
+
 # ---------------------------------------------------------------------------
 # Product events (page tracking). Contract: CentiveAI docs/product-events/CONTRACTS.md
 # ---------------------------------------------------------------------------

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/models/responses.py

@@ -72,3 +72,18 @@ class ProductEventIngestResponse(BaseModel):
     # {"external_user_id", "content", "expires_at"}.
     context: list = Field(default_factory=list)
     raw: Optional[Dict[str, Any]] = None
+
+
+class KbSearchResponse(BaseModel):
+    """evidence packet from POST /anam/kb-search (see CentiveAI kb_grounded_search_service)."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    status: str
+    document_passages: list = Field(default_factory=list)
+    user_messages: list = Field(default_factory=list)
+    answer_rules: str = ""
+    source_policy: str = ""
+    queries: list = Field(default_factory=list)
+    no_evidence_policy: Optional[str] = None
+    raw: Optional[Dict[str, Any]] = None

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/resources/async_sessions.py

@@ -9,12 +9,14 @@ from .._retry import calculate_backoff, extract_retry_after, should_retry
 from ..config import ClientConfig
 from ..exceptions import AuthError, NetworkError, RateLimitError, ServerError, ValidationError
 from ..models.requests import (
+    KbSearchRequest,
     ProductEventBatchRequest,
     SaveMessagesRequest,
     ToolMappingRequest,
     TriggerSessionRequest,
 )
 from ..models.responses import (
+    KbSearchResponse,
     PauseStatusResponse,
     ProductEventIngestResponse,
     SaveMessagesResponse,
@@ -197,6 +199,23 @@ class AsyncSessions:
             raw=data,
         )
 
+    async def kb_search(self, input: KbSearchRequest) -> KbSearchResponse:
+        """Fetches a grounded evidence packet for Aria's client search tool.
+
+        Centive searches the organization's own knowledge folders with several
+        phrasings and validates provenance server-side. Raises the usual SDK
+        errors; the caller reports failure to the persona rather than guessing.
+        """
+        url = join_url(self._config.base_url, self._config.kb_search_path)
+        headers = build_headers(self._config.api_key)
+        # One attempt, no retries: the browser stops waiting for this answer after
+        # 12 s and Anam's tool times out at 15 s, while Centive already spends up
+        # to 8 s searching. A retried 503 would arrive after both have given up.
+        # Chain: Centive 8 s < this timeout (10 s, one attempt) < frontend 12 s < Anam 15 s.
+        response = await self._make_request(url, headers, input.model_dump(exclude_none=True), max_retries=0)
+        data = response.json()
+        return KbSearchResponse(**{key: value for key, value in data.items() if key != "raw"}, raw=data)
+
     async def send_events(self, input: ProductEventBatchRequest) -> ProductEventIngestResponse:
         """Sends a batch of product events (page views) to Centive.
 
@@ -394,12 +413,17 @@ class AsyncSessions:
         ) from last_exception
 
     async def _make_request(
-        self, url: str, headers: dict, payload: dict
+        self, url: str, headers: dict, payload: dict, max_retries: Optional[int] = None
     ) -> httpx.Response:
-        """Makes an HTTP POST request with retry logic and error handling."""
+        """Makes an HTTP POST request with retry logic and error handling.
+
+        ``max_retries`` overrides the configured retry count for calls whose
+        caller has its own deadline (``kb_search`` passes 0).
+        """
         last_exception = None
+        retries = self._config.max_retries if max_retries is None else max_retries
 
-        for attempt in range(self._config.max_retries + 1):
+        for attempt in range(retries + 1):
             try:
                 response = await self._client.post(
                     url,
@@ -440,7 +464,7 @@ class AsyncSessions:
                 elif response.status_code == 429:
                     retry_after = extract_retry_after(response.headers)
 
-                    if should_retry(429, attempt, self._config.max_retries):
+                    if should_retry(429, attempt, retries):
                         delay = (
                             retry_after
                             if retry_after is not None
@@ -467,7 +491,7 @@ class AsyncSessions:
                     )
 
                 elif response.status_code >= 500:
-                    if should_retry(response.status_code, attempt, self._config.max_retries):
+                    if should_retry(response.status_code, attempt, retries):
                         delay = calculate_backoff(
                             attempt, self._config.initial_retry_delay, self._config.max_retry_delay
                         )
@@ -503,7 +527,7 @@ class AsyncSessions:
             except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as e:
                 last_exception = e
 
-                if attempt < self._config.max_retries:
+                if attempt < retries:
                     delay = calculate_backoff(
                         attempt, self._config.initial_retry_delay, self._config.max_retry_delay
                     )
@@ -517,7 +541,7 @@ class AsyncSessions:
                     continue
 
         raise NetworkError(
-            f"Network error after {self._config.max_retries} retries: {str(last_exception)}"
+            f"Network error after {retries} retries: {str(last_exception)}"
         ) from last_exception
 
     def _extract_error_message(self, response: httpx.Response) -> str:

{centive_sdk-2.2.0.dev8 → centive_sdk-2.2.0.dev9}/src/centive_sdk/resources/websocket_server.py

@@ -1,11 +1,12 @@
 import asyncio
 import inspect
 import json
+import re
 import secrets
 import time
 import warnings
 from collections import deque
-from typing import TYPE_CHECKING, Any, Callable, Deque, Dict, Optional, Set, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Deque, Dict, List, Optional, Set, Tuple
 from urllib.parse import parse_qs, urlparse
 
 import websockets
@@ -13,7 +14,10 @@ from websockets.server import WebSocketServerProtocol
 
 from .._logging import safe_log, transport_logger
 from ..config import ClientConfig
+from ..exceptions import CentiveError
 from ..models.requests import (
+    KbSearchFrame,
+    KbSearchRequest,
     SaveMessagesRequest,
     SessionMessage,
     SessionMetadata,
@@ -83,6 +87,10 @@ class WebSocketServer:
         # current_page when the FE's user_trigger frame carries no page of its
         # own (older browser SDKs). Bounded by the number of live connections.
         self._connection_last_page: Dict[WebSocketServerProtocol, dict] = {}
+        # What each browser declared it can serve (e.g. "kb_search"), taken from its
+        # user_trigger frame and forwarded on every trigger-session call for the
+        # connection, so Centive attaches Aria's client tool only where it works.
+        self._connection_capabilities: Dict[WebSocketServerProtocol, List[str]] = {}
         # One Centive trigger-session call per connection start, not two: the
         # connect-time automatic trigger is held back for a grace period and
         # stands down when the client asked itself (_auto_trigger_after_grace);
@@ -610,6 +618,7 @@ class WebSocketServer:
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
             self._connection_last_page.pop(websocket, None)
+            self._connection_capabilities.pop(websocket, None)
             self._connection_triggered.discard(websocket)
             self._connection_trigger_inflight.pop(websocket, None)
             pending_trigger = self._connection_trigger_tasks.pop(websocket, None)
@@ -669,6 +678,10 @@ class WebSocketServer:
             await self._handle_session_end(websocket, data, client_info)
             return
 
+        if msg_type == "kb_search":
+            await self._handle_kb_search(websocket, data, client_info)
+            return
+
         if msg_type == "telemetry":
             # The raw message goes along: the frame byte cap is on what was
             # actually sent, and re-serializing `data` would not reproduce it.
@@ -684,6 +697,81 @@ class WebSocketServer:
             "message": "message received",
         }))
 
+    async def _handle_kb_search(
+        self,
+        websocket: WebSocketServerProtocol,
+        data: dict,
+        client_info: str,
+    ) -> None:
+        """serves Aria's awaited knowledge-search tool.
+
+        The FE SDK sends the user's sentence (prefetch) or the model's own query;
+        Centive answers with an evidence packet scoped to this organization. A
+        failed lookup is reported as an error frame so the persona says that
+        verification failed instead of answering from nothing.
+        """
+        request_id = data.get("request_id") if isinstance(data.get("request_id"), str) else None
+        try:
+            frame = KbSearchFrame.model_validate(data)
+        except Exception as e:  # pydantic ValidationError or wrong shape
+            await websocket.send(json.dumps({
+                "type": "kb_search_response",
+                "request_id": request_id,
+                "status": "error",
+                "error": "INVALID_KB_SEARCH",
+                "message": f"invalid kb_search frame: {str(e)[:200]}",
+            }))
+            return
+
+        if self._config.ws_auth_mode != "open":
+            if await self._enforce_frame_identity(websocket, data, frame.session_id, client_info) is None:
+                return
+
+        request = KbSearchRequest(
+            query=frame.query,
+            alternate_query=frame.alternate_query,
+            user_messages=frame.user_messages,
+            session_id=frame.session_id,
+            external_user_id=frame.user_id,
+        )
+        started = time.monotonic()
+        try:
+            response = await self._sessions.kb_search(request)
+        except CentiveError as e:
+            safe_log(
+                self._logger,
+                "warning",
+                "kb_search failed",
+                {"client": client_info, "request_id": request_id, "error": str(e)[:200]},
+            )
+            await websocket.send(json.dumps({
+                "type": "kb_search_response",
+                "request_id": frame.request_id,
+                "status": "error",
+                "error": "KB_SEARCH_UNAVAILABLE",
+                "message": "knowledge search is unavailable",
+            }))
+            return
+
+        packet = response.raw if response.raw is not None else response.model_dump(exclude={"raw"})
+        safe_log(
+            self._logger,
+            "info",
+            "kb_search served",
+            {
+                "client": client_info,
+                "request_id": frame.request_id,
+                "passages": len(packet.get("document_passages", [])),
+                "seconds": round(time.monotonic() - started, 3),
+            },
+        )
+        await websocket.send(json.dumps({
+            "type": "kb_search_response",
+            "request_id": frame.request_id,
+            "status": "success",
+            "packet": packet,
+        }))
+
     async def _enforce_frame_identity(
         self,
         websocket: WebSocketServerProtocol,
@@ -1424,6 +1512,9 @@ class WebSocketServer:
         # batcher. The frame's own page wins; the last page_view seen on this
         # connection stands in for browser SDKs that predate the field.
         current_page = self._coerce_page(data.get("page")) or self._connection_last_page.get(websocket)
+        declared = self._coerce_capabilities(data.get("capabilities"))
+        if declared:
+            self._connection_capabilities[websocket] = declared
         # The client asked itself, so the connect-time automatic trigger, if it
         # is still waiting out its grace period, has nothing left to do.
         self._connection_triggered.add(websocket)
@@ -1431,6 +1522,17 @@ class WebSocketServer:
             websocket, user_id, user_trigger, client_info, current_page=current_page
         )
 
+    @staticmethod
+    def _coerce_capabilities(value: object) -> Optional[List[str]]:
+        """Bounded list of capability tokens from a frame, or None when nothing usable was declared."""
+        if not isinstance(value, list):
+            return None
+        tokens: List[str] = []
+        for item in value[:16]:
+            if isinstance(item, str) and re.fullmatch(r"[a-z0-9_]{1,32}", item) and item not in tokens:
+                tokens.append(item)
+        return tokens or None
+
     async def _auto_trigger_after_grace(
         self, websocket: WebSocketServerProtocol, user_id: str, client_info: str
     ) -> None:
@@ -1554,6 +1656,7 @@ class WebSocketServer:
                 user_id=user_id,
                 user_trigger=user_trigger,
                 current_page=current_page,
+                capabilities=self._connection_capabilities.get(websocket),
             )
 
             response = await self._sessions.trigger_session(request)

centive_sdk-2.2.0.dev9/tests/test_websocket_capabilities.py

@@ -0,0 +1,80 @@
+"""The browser's declared capabilities ride the user_trigger frame and are forwarded on every
+trigger-session call for that connection; malformed tokens are dropped, nothing declared means the
+field is absent so Centive keeps Anam's built-in tools."""
+
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+import websockets
+
+from centive_sdk import AsyncCentiveClient
+
+WS_PORT = 18791
+
+
+@pytest.fixture
+def trigger_session_response():
+    return {
+        "status": "success",
+        "message": "Session created successfully",
+        "session_data": {"session_id": "sess_123", "token": "tok_abc"},
+        "time_taken": 0.1,
+    }
+
+
+async def _connect(client, base_url, trigger_session_response, pause_status_not_paused_response):
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(return_value=httpx.Response(200, json=pause_status_not_paused_response))
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(return_value=httpx.Response(200, json=trigger_session_response))
+    token = await client.initialize_websocket(user_id="user_123", port=WS_PORT)
+    ws = await websockets.connect(f"ws://localhost:{WS_PORT}/ws?token={token}")
+    first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+    assert first["status"] == "success"  # connect-time session frame
+    return ws, route
+
+
+async def _trigger(ws, frame):
+    await ws.send(json.dumps(frame))
+    for _ in range(5):
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if data.get("status") == "success" and "session_data" in data:
+            return data
+    raise AssertionError("no session frame received")
+
+
+def _last_body(route):
+    return json.loads(route.calls[-1].request.content)
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_declared_capabilities_are_forwarded_and_remembered(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws, route = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        assert "capabilities" not in _last_body(route)  # the automatic connect-time trigger declared nothing
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": ["kb_search", "Bad Token!", 42, "kb_search"]})
+        assert _last_body(route)["capabilities"] == ["kb_search"]
+        # A later trigger on the same connection (a token refresh) keeps the declaration.
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123"})
+        assert _last_body(route)["capabilities"] == ["kb_search"]
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_nothing_usable_declared_means_no_capabilities_field(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws, route = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": ["Not A Token"]})
+        assert "capabilities" not in _last_body(route)
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": "kb_search"})  # wrong shape
+        assert "capabilities" not in _last_body(route)
+    finally:
+        await ws.close()
+        await client.aclose()

centive_sdk-2.2.0.dev9/tests/test_websocket_kb_search.py

@@ -0,0 +1,145 @@
+"""kb_search frames: served from Centive's /anam/kb-search, scoped to the connection's user,
+and reported as an error frame (never a guess) when the lookup fails."""
+
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+import websockets
+
+from centive_sdk import AsyncCentiveClient
+
+WS_PORT = 18790
+
+
+@pytest.fixture
+def trigger_session_response():
+    return {
+        "status": "success",
+        "message": "Session created successfully",
+        "session_data": {"session_id": "sess_123", "token": "tok_abc"},
+        "time_taken": 0.1,
+    }
+
+
+def ws_url(token):
+    return f"ws://localhost:{WS_PORT}/ws?token={token}"
+
+
+PACKET = {
+    "status": "sources_found",
+    "document_passages": [{"document_id": "d1", "chunk_index": 0, "folder_id": "f", "filename": "faqs.md",
+                           "content": "Invite them from Team, Invite Member.", "score": 0.7, "sha256": "h"}],
+    "user_messages": [{"turn_index": 0, "text": "how do I invite", "origin": "user_message", "verified_by_document": False}],
+    "answer_rules": "rules", "source_policy": "policy", "queries": ["how do I invite", "invite"],
+}
+
+
+async def _connect(client, base_url, trigger_session_response, pause_status_not_paused_response):
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(return_value=httpx.Response(200, json=pause_status_not_paused_response))
+    respx.post(f"{base_url}/anam/trigger-session").mock(return_value=httpx.Response(200, json=trigger_session_response))
+    token = await client.initialize_websocket(user_id="user_123", port=WS_PORT)
+    ws = await websockets.connect(ws_url(token))
+    first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+    assert first["status"] == "success"  # connect-time session frame
+    return ws
+
+
+async def _recv_type(ws, frame_type):
+    for _ in range(5):
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if data.get("type") == frame_type:
+            return data
+    raise AssertionError(f"no {frame_type} frame received")
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_frame_is_served_from_centive(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r1", "user_id": "user_123", "session_id": "sess_123",
+                                  "query": "how do I invite", "alternate_query": "invite member", "user_messages": ["how do I invite"]}))
+        frame = await _recv_type(ws, "kb_search_response")
+        assert frame["status"] == "success" and frame["request_id"] == "r1"
+        assert frame["packet"]["document_passages"][0]["document_id"] == "d1"
+        sent = json.loads(route.calls[0].request.content)
+        assert sent == {"query": "how do I invite", "alternate_query": "invite member", "user_messages": ["how do I invite"],
+                        "session_id": "sess_123", "external_user_id": "user_123"}
+        assert route.calls[0].request.headers["X-API-Key"] == api_key
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_failure_is_an_error_frame_after_a_single_attempt(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    """A 503 from Centive is not retried: the browser stops waiting at 12 s and Anam at 15 s,
+    so the error frame must arrive at once rather than after three back-offs."""
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(503, json={"detail": "Knowledge search is unavailable"}))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)  # default retry policy (3) must not apply here
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r2", "user_id": "user_123", "query": "anything"}))
+        frame = await asyncio.wait_for(_recv_type(ws, "kb_search_response"), timeout=3.0)
+        assert frame == {"type": "kb_search_response", "request_id": "r2", "status": "error",
+                         "error": "KB_SEARCH_UNAVAILABLE", "message": "knowledge search is unavailable"}
+        assert route.call_count == 1
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_rejects_bad_frames_and_foreign_identity(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r3", "query": ""}))
+        frame = await _recv_type(ws, "kb_search_response")
+        assert frame["status"] == "error" and frame["error"] == "INVALID_KB_SEARCH" and frame["request_id"] == "r3"
+
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r4", "user_id": "someone_else", "query": "ok"}))
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        assert data["status"] == "error" and data["error"] == "IDENTITY_MISMATCH"
+        assert route.call_count == 0
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_long_chat_message_and_followup_pass_through_without_truncation(
+    base_url, api_key, trigger_session_response, pause_status_not_paused_response,
+):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    question = "q" * 4000
+    history = [question]
+    try:
+        for index, query in enumerate([question, "download invoice"]):
+            if index:
+                history.append(query)
+            await ws.send(json.dumps({
+                "type": "kb_search", "request_id": f"long-{index}", "user_id": "user_123",
+                "query": query, "user_messages": history,
+            }))
+            frame = await _recv_type(ws, "kb_search_response")
+            assert frame["status"] == "success"
+            sent = json.loads(route.calls[index].request.content)
+            assert sent["query"] == query and sent["user_messages"] == history
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "too-long", "query": "q" * 4001}))
+        assert (await _recv_type(ws, "kb_search_response"))["error"] == "INVALID_KB_SEARCH"
+        assert route.call_count == 2
+    finally:
+        await ws.close()
+        await client.aclose()