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

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

@@ -40,6 +40,15 @@ Centive batcher and the host callback).
 
 ### Behavior
 
+- **One trigger-session call per connection start.** The connect-time
+  automatic trigger now waits `session_trigger_grace_seconds` (default 0.5)
+  and stands down when the browser SDK has asked for a session itself in the
+  meantime, which it does the moment its socket opens, with the page it has
+  open. Before, both reached Centive within milliseconds: two Anam tokens per
+  connection and an opening prompt built from the page-less request. A request
+  that lands while another trigger for the same connection is in flight waits
+  for it and receives the same frame. Set the grace to 0 for the old behaviour.
+
 - The telemetry queue has its own circuit breaker, so a failing events
   endpoint cannot stop transcript saves (and vice versa).
 - The queue is bounded (`telemetry_max_queue_events`, default 5000); when full

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.2.0.dev6
+Version: 2.2.0.dev8
 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.dev6 → centive_sdk-2.2.0.dev8}/pyproject.toml

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

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

@@ -83,6 +83,12 @@ class ClientConfig(BaseModel):
     max_session_id_chars: int = 200
     # Concurrent websocket connections accepted per user.
     max_connections_per_user: int = 5
+    # How long the connect-time session trigger waits for the browser SDK to
+    # ask for a session itself before firing. Browser SDKs since 1.0 ask the
+    # moment the socket opens, and their request is the one that carries the
+    # page the user has open; firing first meant two Centive calls and two Anam
+    # tokens per connection. 0 restores the old immediate trigger.
+    session_trigger_grace_seconds: float = 0.5
 
     # Page-telemetry frames (type="telemetry") from the FE SDK. These mirror the
     # aria-sdk producer's own caps (MAX_EVENTS_PER_FRAME, MAX_FRAME_BYTES,

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

@@ -1,3 +1,4 @@
+import asyncio
 import inspect
 import json
 import secrets
@@ -82,6 +83,14 @@ 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] = {}
+        # 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);
+        # a request that lands while another trigger for the same connection is
+        # in flight waits for it and receives the same frame.
+        self._connection_trigger_tasks: Dict[WebSocketServerProtocol, asyncio.Task] = {}
+        self._connection_triggered: set = set()
+        self._connection_trigger_inflight: Dict[WebSocketServerProtocol, asyncio.Future] = {}
         # Every session key touched by a connection, so a disconnect saves all of
         # them rather than only the most recent one.
         self._connection_sessions: Dict[WebSocketServerProtocol, Set[str]] = {}
@@ -569,7 +578,9 @@ class WebSocketServer:
                 {"client": client_info, "user_id": user_id},
             )
 
-            await self._trigger_and_emit(websocket, user_id, None, client_info)
+            self._connection_trigger_tasks[websocket] = asyncio.create_task(
+                self._auto_trigger_after_grace(websocket, user_id, client_info)
+            )
 
         try:
             async for message in websocket:
@@ -599,6 +610,11 @@ class WebSocketServer:
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
             self._connection_last_page.pop(websocket, None)
+            self._connection_triggered.discard(websocket)
+            self._connection_trigger_inflight.pop(websocket, None)
+            pending_trigger = self._connection_trigger_tasks.pop(websocket, None)
+            if pending_trigger is not None:
+                pending_trigger.cancel()
             self._telemetry_rate.forget(websocket)
             session_keys = self._connection_sessions.pop(websocket, set())
 
@@ -1408,10 +1424,47 @@ 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)
+        # 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)
         await self._trigger_and_emit(
             websocket, user_id, user_trigger, client_info, current_page=current_page
         )
 
+    async def _auto_trigger_after_grace(
+        self, websocket: WebSocketServerProtocol, user_id: str, client_info: str
+    ) -> None:
+        """The connect-time session trigger, held back briefly.
+
+        Browser SDKs since 1.0 ask for a token themselves the moment the socket
+        opens, and that request is the one that carries the page the user has
+        open. Firing the automatic trigger first (and before the message loop
+        even started reading) meant two Centive calls and two Anam tokens per
+        connection, with the opening prompt built from the page-less one. Now
+        the automatic trigger waits config.session_trigger_grace_seconds and
+        stands down when the client has asked in the meantime. A client that
+        never asks (older SDKs, custom frontends) still gets its session, half
+        a second later.
+        """
+        try:
+            grace = max(0.0, float(self._config.session_trigger_grace_seconds or 0))
+            if grace:
+                await asyncio.sleep(grace)
+            if websocket in self._connection_triggered or not self._is_live(websocket):
+                safe_log(
+                    self._logger,
+                    "info",
+                    "automatic session trigger stood down",
+                    {"client": client_info, "user_id": user_id,
+                     "reason": "client asked" if websocket in self._connection_triggered else "connection gone"},
+                )
+                return
+            await self._trigger_and_emit(websocket, user_id, None, client_info)
+        except asyncio.CancelledError:
+            return
+        finally:
+            self._connection_trigger_tasks.pop(websocket, None)
+
     def _remember_page(self, websocket: WebSocketServerProtocol, events: Any) -> None:
         """Keeps the newest page_view's page for this connection (see _handle_user_trigger)."""
         if not isinstance(events, list):
@@ -1444,7 +1497,50 @@ class WebSocketServer:
         client_info: str,
         current_page: Optional[dict] = None,
     ) -> None:
-        """calls trigger_session API and emits response to FE."""
+        """calls trigger_session API and emits response to FE.
+
+        Two triggers for the same connection at once (the automatic one mid
+        call when the client's own request lands) share one Centive call: the
+        second waits for the first and re-emits its frame.
+        """
+        inflight = self._connection_trigger_inflight.get(websocket)
+        if inflight is not None:
+            safe_log(
+                self._logger,
+                "info",
+                "session trigger coalesced with one in flight",
+                {"client": client_info, "user_id": user_id},
+            )
+            try:
+                frame = await asyncio.shield(inflight)
+            except Exception:  # noqa: BLE001 - the first caller already reported it
+                frame = None
+            if frame is not None:
+                try:
+                    await websocket.send(frame)
+                except Exception:  # noqa: BLE001
+                    pass
+            return
+
+        done: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._connection_trigger_inflight[websocket] = done
+        emitted: Optional[str] = None
+        try:
+            emitted = await self._trigger_once(websocket, user_id, user_trigger, client_info, current_page)
+        finally:
+            self._connection_trigger_inflight.pop(websocket, None)
+            if not done.done():
+                done.set_result(emitted)
+
+    async def _trigger_once(
+        self,
+        websocket: WebSocketServerProtocol,
+        user_id: str,
+        user_trigger: Optional[bool],
+        client_info: str,
+        current_page: Optional[dict],
+    ) -> Optional[str]:
+        """One trigger-session call. Returns the success frame it sent, if any."""
         safe_log(
             self._logger,
             "info",
@@ -1481,7 +1577,7 @@ class WebSocketServer:
                     "message": "failed to trigger session",
                     "error": "UPSTREAM_TRIGGER_FAILED",
                 }))
-                return
+                return None
 
             response_data = {
                 "status": response.status,
@@ -1490,7 +1586,8 @@ class WebSocketServer:
                 "time_taken": response.time_taken,
             }
 
-            await websocket.send(json.dumps(response_data))
+            frame = json.dumps(response_data)
+            await websocket.send(frame)
 
             safe_log(
                 self._logger,
@@ -1503,6 +1600,7 @@ class WebSocketServer:
                     "has_session_data": response.session_data is not None,
                 },
             )
+            return frame
 
         except Exception as e:
             # Generic on the wire, detailed in the server's own logs: upstream

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev8}/tests/test_websocket_server.py

@@ -127,31 +127,134 @@ async def test_user_trigger_forwards_the_browsers_page(base_url, api_key, ws_por
     client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
     token = await client.initialize_websocket(user_id="user_123", port=ws_port)
 
-    async with websockets.connect(ws_url(ws_port, token)) as ws:
-        await ws.recv()  # auto-trigger on connect: no page known yet
-        assert "current_page" not in json.loads(route.calls.last.request.content)
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.recv()  # auto-trigger on connect: no page known yet
+            assert "current_page" not in json.loads(route.calls.last.request.content)
+
+            await ws.send(json.dumps({
+                "user_trigger": True,
+                "page": {"path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices",
+                         "referrer_path": "/home", "junk": "ignored"},
+            }))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            body = json.loads(route.calls.last.request.content)
+            assert body["external_user_id"] == "user_123"
+            assert body["current_page"] == {
+                "path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices", "referrer_path": "/home",
+            }
+
+            # A malformed hint costs nothing: the session is still triggered, without it.
+            await ws.send(json.dumps({"user_trigger": True, "page": {"pattern": 7}}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+            assert "current_page" not in json.loads(route.calls.last.request.content)
+
+    finally:
+        await client.aclose()
 
-        await ws.send(json.dumps({
-            "user_trigger": True,
-            "page": {"path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices",
-                     "referrer_path": "/home", "junk": "ignored"},
-        }))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
 
-        body = json.loads(route.calls.last.request.content)
-        assert body["external_user_id"] == "user_123"
-        assert body["current_page"] == {
-            "path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices", "referrer_path": "/home",
-        }
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_client_that_asks_for_its_session_replaces_the_automatic_trigger(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """One Centive call per connection start, carrying the page.
 
-        # A malformed hint costs nothing: the session is still triggered, without it.
-        await ws.send(json.dumps({"user_trigger": True, "page": {"pattern": 7}}))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
+    Seen on dev: the connect-time automatic trigger and the browser SDK's own
+    request (sent the moment the socket opens) both reached Centive within
+    milliseconds, two Anam tokens per connection, and the opening prompt was
+    built from the page-less one.
+    """
+    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)
+    )
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.send(json.dumps({"user_trigger": True, "page": {"path": "/dashboard", "pattern": "/dashboard"}}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            # Past the grace period nothing else arrives: the automatic trigger stood down.
+            with pytest.raises(asyncio.TimeoutError):
+                await asyncio.wait_for(ws.recv(), timeout=client.config.session_trigger_grace_seconds + 0.7)
+
+        assert route.call_count == 1
+        assert json.loads(route.calls.last.request.content)["current_page"]["path"] == "/dashboard"
+    finally:
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_silent_client_still_gets_the_automatic_trigger(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """Older browser SDKs and custom frontends never ask; they get their session
+    after the grace period, from exactly one call."""
+    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)
+    )
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+            assert data["session_data"]["token"] == trigger_session_response["session_data"]["token"]
+
+        assert route.call_count == 1
         assert "current_page" not in json.loads(route.calls.last.request.content)
+    finally:
+        await client.aclose()
 
-    await client.aclose()
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_concurrent_triggers_on_one_connection_share_a_call(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """A request that lands while another trigger for the connection is in
+    flight waits for it and receives the same frame; Centive is called once."""
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(
+        return_value=httpx.Response(200, json=pause_status_not_paused_response)
+    )
+
+    async def slow(request):
+        await asyncio.sleep(0.4)
+        return httpx.Response(200, json=trigger_session_response)
+
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(side_effect=slow)
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    client.config.session_trigger_grace_seconds = 0  # automatic trigger fires at once
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.send(json.dumps({"user_trigger": True}))  # lands while the automatic call is in flight
+            first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            second = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert first["status"] == second["status"] == "success"
+            assert first["session_data"] == second["session_data"]
+
+        assert route.call_count == 1
+    finally:
+        await client.aclose()
 
 
 @pytest.mark.asyncio
@@ -174,23 +277,25 @@ async def test_user_trigger_falls_back_to_the_last_page_view_seen(
     client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
     token = await client.initialize_websocket(user_id="user_123", port=ws_port)
 
-    async with websockets.connect(ws_url(ws_port, token)) as ws:
-        await ws.recv()
-        frame = dict(telemetry_event_data)
-        await ws.send(json.dumps(frame))
-        ack = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert ack["type"] == "telemetry_ack"
-
-        await ws.send(json.dumps({"user_trigger": True}))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
-
-        body = json.loads(route.calls.last.request.content)
-        latest_view = [e for e in frame["events"] if e["event_type"] == "page_view"][-1]["page"]
-        assert body["current_page"]["path"] == latest_view["path"]
-        assert body["current_page"]["pattern"] == latest_view["pattern"]
-
-    await client.aclose()
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.recv()
+            frame = dict(telemetry_event_data)
+            await ws.send(json.dumps(frame))
+            ack = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert ack["type"] == "telemetry_ack"
+
+            await ws.send(json.dumps({"user_trigger": True}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            body = json.loads(route.calls.last.request.content)
+            latest_view = [e for e in frame["events"] if e["event_type"] == "page_view"][-1]["page"]
+            assert body["current_page"]["path"] == latest_view["path"]
+            assert body["current_page"]["pattern"] == latest_view["pattern"]
+
+    finally:
+        await client.aclose()
 
 
 @pytest.mark.asyncio