soothe-client-python 0.9.4__py3-none-any.whl

soothe_client/appkit/events.py

@@ -0,0 +1,63 @@
+"""Protocol-1 streaming frame helpers for application loops."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def unwrap_next(event: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Unwrap a protocol-1 ``next`` envelope to its inner streaming frame.
+
+    Under protocol-1 the daemon wraps free-form streaming frames
+    (``event`` / ``command_response`` / card replay) in a
+    ``{proto, type:"next", payload:{namespace, mode, data}}`` envelope. This
+    helper returns the inner ``data`` dict (the legacy frame) so turn loops
+    can branch on the same fields as before the migration.
+
+    ``status`` / ``error`` / ``response`` / ``complete`` are sent raw and pass
+    through unchanged.
+
+    Args:
+        event: A raw wire frame as returned by ``client.read_event()``.
+
+    Returns:
+        The inner ``payload.data`` dict for ``next`` envelopes, the original
+        frame otherwise, or ``None`` if ``event`` is ``None``.
+    """
+    if not isinstance(event, dict):
+        return event
+    if event.get("type") != "next":
+        return event
+    payload = event.get("payload")
+    if not isinstance(payload, dict):
+        return event
+    data = payload.get("data")
+    return data if isinstance(data, dict) else event
+
+
+def is_loop_scoped_event(event: dict[str, Any], *, active_loop_id: str) -> bool:
+    """Return whether a daemon frame belongs to the active StrangeLoop session.
+
+    Unwraps protocol-1 ``next`` envelopes first, then checks ``loop_id`` on the
+    inner streaming frame. Non-scoped types (``response``, ``error``,
+    ``complete``, etc.) are always considered in-scope.
+
+    Args:
+        event: Raw or already-unwrapped wire frame.
+        active_loop_id: Loop id for the in-flight session.
+
+    Returns:
+        True when the frame should be processed for ``active_loop_id``.
+    """
+    event_type = event.get("type", "")
+    if event_type == "next":
+        inner = unwrap_next(event)
+        if isinstance(inner, dict):
+            event_type = inner.get("type", "")
+            return event_type not in {"status", "event"} or (inner.get("loop_id") == active_loop_id)
+    if event_type not in {"status", "event"}:
+        return True
+    return event.get("loop_id") == active_loop_id
+
+
+__all__ = ["is_loop_scoped_event", "unwrap_next"]

soothe_client/appkit/managed_client.py

@@ -0,0 +1,163 @@
+"""ManagedClient seam for appkit ConnectionPool / TurnRunner (RFC-629).
+
+The concrete ``WebSocketClient`` satisfies it via ``WebSocketManagedClient``;
+tests supply fakes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+from soothe_client.errors import DisconnectCause
+from soothe_client.websocket import WebSocketClient
+
+ClientFactory = Callable[[str], "ManagedClient"]
+BootstrapFunc = Callable[
+    ["ManagedClient", str, str],
+    Awaitable[str],
+]
+
+
+@runtime_checkable
+class ManagedClient(Protocol):
+    """Subset of Layer 0 that ConnectionPool and TurnRunner depend on."""
+
+    async def connect(self) -> None:
+        """Dial and handshake."""
+        ...
+
+    async def reconnect(self) -> None:
+        """Re-dial after a drop."""
+        ...
+
+    async def reattach_and_probe(self, loop_id: str) -> None:
+        """Resume a loop by id and probe liveness."""
+        ...
+
+    async def send_message(self, msg: Any) -> None:
+        """Send a fire-and-forget JSON frame (legacy flat or wire envelope)."""
+        ...
+
+    def receive_messages(
+        self,
+        *,
+        cancel_event: Any | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield decoded daemon events until EOF or cancel."""
+        ...
+
+    def is_disconnected(self) -> bool:
+        """Return whether the disconnect signal has fired."""
+        ...
+
+    def disconnect_cause(self) -> DisconnectCause | None:
+        """Return the disconnect cause, or None if still connected."""
+        ...
+
+    def is_connected(self) -> bool:
+        """Report connection liveness."""
+        ...
+
+    async def close(self) -> None:
+        """Tear down the connection."""
+        ...
+
+
+class WebSocketManagedClient:
+    """Adapter wrapping ``WebSocketClient`` as a ``ManagedClient``."""
+
+    def __init__(self, client: WebSocketClient) -> None:
+        self._client = client
+
+    @property
+    def underlying(self) -> WebSocketClient:
+        """Return the wrapped Layer 0 client."""
+        return self._client
+
+    async def connect(self) -> None:
+        await self._client.connect()
+        await self._client.request_connection_init()
+        await self._client.wait_for_connection_ack()
+
+    async def reconnect(self) -> None:
+        await self._client.reconnect()
+
+    async def reattach_and_probe(self, loop_id: str) -> None:
+        await self._client.reattach_and_probe(loop_id)
+
+    async def send_message(self, msg: Any) -> None:
+        if not isinstance(msg, dict):
+            raise TypeError("send_message expects a dict payload")
+        await self._client.send(msg)
+
+    async def receive_messages(
+        self,
+        *,
+        cancel_event: Any | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        while True:
+            if cancel_event is not None and cancel_event.is_set():
+                return
+            event = await self._client.read_event()
+            if event is None:
+                return
+            yield event
+
+    def is_disconnected(self) -> bool:
+        return self._client.is_disconnected()
+
+    def disconnect_cause(self) -> DisconnectCause | None:
+        return self._client.disconnect_cause()
+
+    def is_connected(self) -> bool:
+        alive = getattr(self._client, "is_connection_alive", None)
+        if callable(alive):
+            return bool(alive()) and not self._client.is_disconnected()
+        return bool(self._client.is_connected) and not self._client.is_disconnected()
+
+    async def close(self) -> None:
+        await self._client.close()
+
+
+def default_client_factory() -> ClientFactory:
+    """Return a factory that builds ``WebSocketManagedClient`` instances."""
+
+    def _factory(url: str) -> ManagedClient:
+        return WebSocketManagedClient(WebSocketClient(url=url))
+
+    return _factory
+
+
+def default_bootstrap_func() -> BootstrapFunc:
+    """Default bootstrap: ``loop_new`` + ``subscribe(loop_events)``."""
+
+    async def _bootstrap(client: ManagedClient, workspace_id: str, user_id: str) -> str:
+        from soothe_client.session import bootstrap_loop_session
+
+        underlying = getattr(client, "underlying", client)
+        status = await bootstrap_loop_session(
+            underlying,
+            resume_loop_id=None,
+            user_id=user_id or None,
+            client_workspace_id=workspace_id or None,
+            workspace=workspace_id or None,
+        )
+        if status.get("type") == "error":
+            raise RuntimeError(str(status.get("message", "daemon bootstrap failed")))
+        loop_id = str(status.get("loop_id") or "").strip()
+        if not loop_id:
+            raise RuntimeError("bootstrap_loop_session returned no loop_id")
+        return loop_id
+
+    return _bootstrap
+
+
+__all__ = [
+    "BootstrapFunc",
+    "ClientFactory",
+    "ManagedClient",
+    "WebSocketManagedClient",
+    "default_bootstrap_func",
+    "default_client_factory",
+]

soothe_client/appkit/observability.py

@@ -0,0 +1,29 @@
+"""Per-turn observability counters for daemon stream consumption."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TurnEventStats:
+    """Event counts accumulated over a single daemon turn.
+
+    Apps may subclass or replace this via ``DaemonSession``'s stats factory.
+    """
+
+    total: int = 0
+    messages: int = 0
+    updates: int = 0
+    custom: int = 0
+    skipped: int = 0
+    filtered_early: int = 0
+    tool_calls: int = 0
+    tool_results: int = 0
+    text_chunks: int = 0
+    heartbeats_dropped: int = 0
+    post_idle_drained: int = 0
+    inbound_dropped: int = 0
+
+
+__all__ = ["TurnEventStats"]

soothe_client/appkit/pool.py

@@ -0,0 +1,258 @@
+"""Per-session connection pool for appkit (RFC-629 Layer 1).
+
+Manages a pool of daemon connections, one active per session. Reuses an
+active connection when still live, otherwise bootstraps a fresh loop or
+reattaches an existing one. Persistence of session↔loop mappings is
+abstracted behind ``SessionStore``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from soothe_client.appkit.managed_client import (
+    BootstrapFunc,
+    ClientFactory,
+    ManagedClient,
+    default_bootstrap_func,
+    default_client_factory,
+)
+from soothe_client.appkit.session_store import SessionStore
+from soothe_client.errors import StaleLoopError
+
+
+class ErrPoolExhausted(Exception):  # noqa: N818 — match Go/TS name
+    """Raised when no free connection slot is available."""
+
+    def __init__(self) -> None:
+        super().__init__("appkit: connection pool exhausted")
+
+
+@dataclass(slots=True)
+class PoolConfig:
+    """Configures a ``ConnectionPool``. Zero / negative sizes use defaults."""
+
+    pool_size: int = 1000
+    query_timeout_s: float = 30 * 60
+    connection_timeout_s: float = 30.0
+    max_idle_time_s: float = 10 * 60
+    health_check_interval_s: float = 30.0
+
+
+def default_pool_config() -> PoolConfig:
+    """Return conservative pool defaults suitable for most apps."""
+    return PoolConfig()
+
+
+class PooledConn:
+    """One connection slot in the pool."""
+
+    __slots__ = (
+        "slot_id",
+        "client",
+        "event_stream",
+        "stream_cancel",
+        "session_id",
+        "loop_id",
+        "workspace_id",
+        "last_used",
+    )
+
+    def __init__(self, slot_id: int, client: ManagedClient) -> None:
+        self.slot_id = slot_id
+        self.client = client
+        self.event_stream: AsyncIterator[dict[str, Any]] | None = None
+        self.stream_cancel: asyncio.Event | None = None
+        self.session_id = ""
+        self.loop_id = ""
+        self.workspace_id = ""
+        self.last_used = 0.0
+
+    def is_disconnected(self) -> bool:
+        """Report whether the underlying client signalled a drop."""
+        return self.client.is_disconnected()
+
+    def is_connected(self) -> bool:
+        """Report whether the slot is still usable."""
+        return self.client.is_connected() and not self.is_disconnected()
+
+    def get_loop_id(self) -> str:
+        """Return the active loop id for this slot."""
+        return self.loop_id
+
+
+class ConnectionPool:
+    """Manage a pool of daemon connections, one active per session."""
+
+    def __init__(
+        self,
+        url: str,
+        store: SessionStore,
+        cfg: PoolConfig | None = None,
+        factory: ClientFactory | None = None,
+    ) -> None:
+        self._cfg = cfg or default_pool_config()
+        if self._cfg.pool_size <= 0:
+            self._cfg = PoolConfig(
+                pool_size=default_pool_config().pool_size,
+                query_timeout_s=self._cfg.query_timeout_s,
+                connection_timeout_s=self._cfg.connection_timeout_s,
+                max_idle_time_s=self._cfg.max_idle_time_s,
+                health_check_interval_s=self._cfg.health_check_interval_s,
+            )
+        self._factory = factory or default_client_factory()
+        self._bootstrap: BootstrapFunc = default_bootstrap_func()
+        self._store = store
+        self._url = url
+        self._pool: list[PooledConn] = []
+        self._active: dict[str, PooledConn] = {}
+        self._next_slot_id = 1
+        self._lock = asyncio.Lock()
+        for _ in range(self._cfg.pool_size):
+            self._pool.append(self._new_slot())
+
+    def with_bootstrap(self, bootstrap: BootstrapFunc) -> ConnectionPool:
+        """Override the loop bootstrap function (useful for test fakes)."""
+        self._bootstrap = bootstrap
+        return self
+
+    def with_client_factory(self, factory: ClientFactory) -> ConnectionPool:
+        """Override the client factory (useful for test fakes)."""
+        self._factory = factory
+        return self
+
+    def stats(self) -> dict[str, int]:
+        """Return a snapshot of active and idle slot counts."""
+        return {"active": len(self._active), "idle": len(self._pool)}
+
+    def _new_slot(self) -> PooledConn:
+        slot_id = self._next_slot_id
+        self._next_slot_id += 1
+        return PooledConn(slot_id, self._factory(self._url))
+
+    async def acquire(
+        self,
+        session_id: str,
+        workspace_id: str,
+        user_id: str,
+    ) -> PooledConn:
+        """Return a live connection for ``session_id``.
+
+        Caller must ``release`` when done (turn completes or session reset).
+        """
+        async with self._lock:
+            existing = self._active.get(session_id)
+            if existing is not None:
+                if existing.is_disconnected() or not existing.is_connected():
+                    await self._release_unlocked(session_id)
+                else:
+                    existing.last_used = time.monotonic()
+                    with contextlib.suppress(Exception):
+                        await self._store.update_last_used(session_id)
+                    return existing
+
+            if not self._pool:
+                raise ErrPoolExhausted()
+            conn = self._pool.pop()
+            self._active[session_id] = conn
+
+        loop_id = ""
+        ok = False
+        with contextlib.suppress(Exception):
+            loop_id, ok = await self._store.get_loop_id_for_session(session_id)
+
+        final_loop_id = ""
+        try:
+            if not ok or not loop_id:
+                await conn.client.connect()
+                final_loop_id = await self._bootstrap_new(conn, workspace_id, user_id)
+                with contextlib.suppress(Exception):
+                    await self._store.create_session(workspace_id, session_id, final_loop_id, "")
+            else:
+                try:
+                    await self._resume_and_reattach(conn, loop_id)
+                    final_loop_id = loop_id
+                except Exception:
+                    await conn.client.connect()
+                    final_loop_id = await self._bootstrap_new(conn, workspace_id, user_id)
+                    with contextlib.suppress(Exception):
+                        await self._store.create_session(
+                            workspace_id, session_id, final_loop_id, ""
+                        )
+        except Exception:
+            await self.release(session_id)
+            raise
+
+        conn.session_id = session_id
+        conn.loop_id = final_loop_id
+        conn.workspace_id = workspace_id
+        conn.last_used = time.monotonic()
+        with contextlib.suppress(Exception):
+            await self._store.update_last_used(session_id)
+        return conn
+
+    async def release(self, session_id: str) -> None:
+        """Tear down the connection for ``session_id`` and return a fresh slot."""
+        async with self._lock:
+            await self._release_unlocked(session_id)
+
+    async def _release_unlocked(self, session_id: str) -> None:
+        conn = self._active.pop(session_id, None)
+        if conn is None:
+            return
+        if conn.stream_cancel is not None:
+            conn.stream_cancel.set()
+            conn.stream_cancel = None
+        with contextlib.suppress(Exception):
+            await conn.client.close()
+        conn.session_id = ""
+        conn.loop_id = ""
+        conn.event_stream = None
+        self._pool.append(self._new_slot())
+
+    async def reset_session(self, session_id: str) -> None:
+        """Tear down so the next acquire bootstraps fresh."""
+        await self.release(session_id)
+
+    async def stop(self) -> None:
+        """Gracefully shut down all active connections."""
+        async with self._lock:
+            for sid in list(self._active):
+                await self._release_unlocked(sid)
+
+    async def _bootstrap_new(
+        self,
+        conn: PooledConn,
+        workspace_id: str,
+        user_id: str,
+    ) -> str:
+        loop_id = await self._bootstrap(conn.client, workspace_id, user_id)
+        self._start_reader(conn)
+        return loop_id
+
+    async def _resume_and_reattach(self, conn: PooledConn, loop_id: str) -> None:
+        await conn.client.connect()
+        try:
+            await conn.client.reattach_and_probe(loop_id)
+        except StaleLoopError:
+            raise
+        self._start_reader(conn)
+
+    def _start_reader(self, conn: PooledConn) -> None:
+        cancel = asyncio.Event()
+        conn.stream_cancel = cancel
+        conn.event_stream = conn.client.receive_messages(cancel_event=cancel)
+
+
+__all__ = [
+    "ConnectionPool",
+    "ErrPoolExhausted",
+    "PoolConfig",
+    "PooledConn",
+    "default_pool_config",
+]

soothe_client/appkit/query_gate.py

@@ -0,0 +1,93 @@
+"""Single-flight query gate (RFC-629 Layer 1)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+SendCancelFn = Callable[[], Awaitable[None] | None]
+
+
+class ErrQueryBusy(Exception):  # noqa: N818 — match Go/TS `ErrQueryBusy` name
+    """Raised when a session already has an in-flight query."""
+
+    def __init__(self) -> None:
+        super().__init__("appkit: query already in progress for session")
+
+
+class QueryGate:
+    """Enforce single-flight query execution per session id.
+
+    Cancel ordering: daemon cancel (detached timeout) runs before the local
+    cancel callback, matching Go/TS appkit semantics.
+    """
+
+    def __init__(self, *, cancel_timeout_s: float = 10.0) -> None:
+        self._lock = asyncio.Lock()
+        self._cancels: dict[str, Callable[[], None]] = {}
+        self._send_cancels: dict[str, SendCancelFn] = {}
+        self._cancel_timeout_s = cancel_timeout_s
+
+    async def acquire(
+        self,
+        session_id: str,
+        cancel: Callable[[], None],
+        send_cancel: SendCancelFn | None = None,
+    ) -> None:
+        """Reserve ``session_id`` for one agent turn.
+
+        Args:
+            session_id: Application session key (often the loop id).
+            cancel: Local cancel callback (e.g. set an Event / cancel a task).
+            send_cancel: Optional async daemon-cancel sender.
+
+        Raises:
+            ErrQueryBusy: A query is already in flight for ``session_id``.
+        """
+        async with self._lock:
+            if session_id in self._cancels:
+                raise ErrQueryBusy()
+            self._cancels[session_id] = cancel
+            if send_cancel is not None:
+                self._send_cancels[session_id] = send_cancel
+
+    async def cancel(self, session_id: str) -> None:
+        """Stop an in-flight query: daemon cancel first, then local cancel."""
+        async with self._lock:
+            cancel = self._cancels.pop(session_id, None)
+            send_cancel = self._send_cancels.pop(session_id, None)
+
+        if cancel is None and send_cancel is None:
+            return
+
+        if send_cancel is not None:
+            try:
+                await asyncio.wait_for(
+                    _await_maybe(send_cancel()),
+                    timeout=self._cancel_timeout_s,
+                )
+            except Exception:  # noqa: BLE001 — proceed to local cancel
+                pass
+
+        if cancel is not None:
+            cancel()
+
+    async def release(self, session_id: str) -> None:
+        """Clear the gate without sending a daemon cancel."""
+        async with self._lock:
+            self._cancels.pop(session_id, None)
+            self._send_cancels.pop(session_id, None)
+
+    async def is_active(self, session_id: str) -> bool:
+        """Return whether a query is in flight for ``session_id``."""
+        async with self._lock:
+            return session_id in self._cancels
+
+
+async def _await_maybe(result: Any) -> None:
+    if asyncio.iscoroutine(result) or isinstance(result, Awaitable):
+        await result  # type: ignore[misc]
+
+
+__all__ = ["ErrQueryBusy", "QueryGate"]