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

soothe_client/__init__.py

@@ -1,8 +1,7 @@
-"""Soothe WebSocket client for soothe-daemon.
+"""Soothe WebSocket client for talking to a running soothe-daemon.
 
-Layer 0 transport and session helpers. Layer 1 application mechanics live in
-``soothe_client.appkit``. Shared wire codec and path constants live in
-soothe-sdk (`soothe_sdk.wire`, `soothe_sdk.paths`).
+Transport helpers (connect, loops, RPCs) live here. Higher-level session
+and multi-user turn tools live in ``soothe_client.appkit``.
 """
 
 from __future__ import annotations
@@ -21,12 +20,14 @@ from soothe_client.errors import (
 )
 from soothe_client.helpers import (
     check_daemon_status,
+    connected_websocket,
     fetch_config_section,
     fetch_loop_cards,
     fetch_loop_history,
     fetch_loop_messages,
     fetch_skills_catalog,
     is_daemon_live,
+    protocol1_rpc,
     request_daemon_config_reload,
     request_daemon_shutdown,
     websocket_url_from_config,
@@ -42,7 +43,17 @@ from soothe_client.intent_hints import (
 from soothe_client.protocol_params import (
     AuthParams,
     AuthRefreshParams,
+    AutopilotCancelGoalParams,
+    AutopilotDreamParams,
+    AutopilotGetGoalParams,
+    AutopilotGetJobParams,
+    AutopilotListGoalsParams,
+    AutopilotListJobsParams,
+    AutopilotResumeParams,
+    AutopilotStatusParams,
+    AutopilotSubmitParams,
     AutopilotSubscribeParams,
+    AutopilotWakeParams,
     ConfigGetParams,
     ConfigReloadParams,
     CronAddParams,
@@ -114,6 +125,8 @@ __all__ = [
     "bootstrap_loop_session",
     "connect_websocket_with_retries",
     "websocket_url_from_config",
+    "connected_websocket",
+    "protocol1_rpc",
     "check_daemon_status",
     "is_daemon_live",
     "request_daemon_config_reload",
@@ -144,6 +157,16 @@ __all__ = [
     "LoopDetachParams",
     "SubscribeParams",
     "AutopilotSubscribeParams",
+    "AutopilotStatusParams",
+    "AutopilotSubmitParams",
+    "AutopilotListGoalsParams",
+    "AutopilotGetGoalParams",
+    "AutopilotCancelGoalParams",
+    "AutopilotWakeParams",
+    "AutopilotDreamParams",
+    "AutopilotResumeParams",
+    "AutopilotListJobsParams",
+    "AutopilotGetJobParams",
     "JobCreateParams",
     "JobStatusParams",
     "JobPauseParams",

soothe_client/appkit/__init__.py

@@ -1,15 +1,12 @@
-"""Reusable application-architecture layer over Layer 0 (RFC-629).
+"""Application helpers built on WebSocketClient.
 
-appkit is product-agnostic. Deliverable phases, persistence, and UI copy stay
-in the application (e.g. soothe-cli). Building blocks:
+Product-agnostic building blocks for agent UIs and backends:
 
-- ``unwrap_next`` / ``is_loop_scoped_event`` — protocol-1 stream helpers
-- ``QueryGate`` — single-flight cancel-before-context gating
-- ``TurnEventPipeline`` — reader / processor / applier concurrency
-- ``DaemonSession`` — dual-socket loop session + ``iter_turn_chunks``
-- ``EventClassifier`` / ``extract_thinking_step`` — deliverable terminal mapping
-- ``SSEBroadcaster`` — drop-on-full SSE-style fan-out
-- ``ConnectionPool`` / ``TurnRunner`` — pooled multi-session turn execution
+- ``DaemonSession`` — dual-socket loop session + streamed turns
+- ``ConnectionPool`` / ``TurnRunner`` — multi-session turn execution
+- ``QueryGate`` — one-in-flight query per session
+- ``EventClassifier`` / ``extract_thinking_step`` — stream → deliverable mapping
+- ``SSEBroadcaster`` — drop-on-full fan-out to subscribers
 - ``SessionStore`` — persistence seam (Protocol)
 """
 

soothe_client/appkit/attachments.py

@@ -1,8 +1,7 @@
-"""Image attachment compaction for appkit (RFC-629 Layer 1).
+"""Image attachment compaction for appkit.
 
 Downscales ``image/*`` payloads when either dimension exceeds a max size.
-Non-images and decode failures pass through unchanged. Requires Pillow when
-compaction is requested; without Pillow, inputs are returned unchanged.
+Non-images and decode failures pass through unchanged.
 """
 
 from __future__ import annotations
@@ -12,6 +11,8 @@ import io
 from dataclasses import dataclass
 from typing import Any
 
+from PIL import Image
+
 
 @dataclass(slots=True)
 class CompactImageOptions:
@@ -49,10 +50,6 @@ def compact_image_attachment(
     """
     if not data_b64 or not mime_type.startswith("image/"):
         return mime_type, data_b64
-    try:
-        from PIL import Image
-    except ImportError:
-        return mime_type, data_b64
 
     try:
         raw = base64.b64decode(data_b64, validate=False)

soothe_client/appkit/broadcaster.py

@@ -1,4 +1,4 @@
-"""SSE-style pub/sub fan-out for appkit (RFC-629 Layer 1).
+"""SSE-style pub/sub fan-out for appkit.
 
 Generic, string-keyed pub/sub for SSE-style event delivery. Slow consumers do
 not stall the broadcaster: each subscriber has a bounded queue and overflowing

soothe_client/appkit/classifier.py

@@ -1,4 +1,4 @@
-"""Event classifier for appkit (RFC-629 Layer 1).
+"""Event classifier for appkit.
 
 Maps a stream of decoded daemon events into deliverable/streaming/terminal
 outcomes, keyed on (namespace, mode, phase). Product apps pass their own

soothe_client/appkit/daemon_session.py

@@ -1,9 +1,8 @@
-"""Dual-socket daemon loop session with turn streaming (CLI-grade mechanics).
+"""Dual-socket daemon loop session with turn streaming.
 
 Owns a subscribed stream WebSocket plus an RPC sidecar so metadata calls do not
-starve ``loop_events``. ``iter_turn_chunks`` implements stale-idle guarding,
-post-idle drain, loop scoping, and connection-loss detection — behavior that
-originated in soothe-cli and is not yet mirrored in Go/TS TurnRunner.
+starve loop events. ``iter_turn_chunks`` handles idle timeout, post-idle drain,
+loop scoping, and connection-loss detection.
 """
 
 from __future__ import annotations
@@ -25,7 +24,12 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_POST_IDLE_DRAIN_S = 0.5
 _RPC_HANDSHAKE_TIMEOUT_S = 20.0
-_TURN_END_CUSTOM_TYPES = frozenset({"soothe.cognition.strange_loop.completed"})
+_TURN_END_CUSTOM_TYPES = frozenset(
+    {
+        "soothe.cognition.strange_loop.completed",
+        "soothe.stream.end",
+    }
+)
 
 EarlyDropFn = Callable[[tuple[Any, ...], str, Any], bool]
 StatsFactory = Callable[[], Any]
@@ -210,6 +214,7 @@ class DaemonSession:
         clarification_mode: str | None = None,
         clarification_answer: bool = False,
         clarification_answers: list[str] | None = None,
+        intent_hint: str | None = None,
     ) -> None:
         """Send a new user turn to the daemon."""
         if not self._loop_id:
@@ -227,6 +232,7 @@ class DaemonSession:
             clarification_mode=clarification_mode,
             clarification_answer=clarification_answer,
             clarification_answers=clarification_answers,
+            intent_hint=intent_hint,
         )
 
     async def cancel_remote_query(self) -> None:
@@ -289,8 +295,19 @@ class DaemonSession:
             await self._ensure_rpc_connected()
             return await self._rpc_client.request("loop_list", {"limit": limit}, timeout=15.0)
 
-    async def iter_turn_chunks(self) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
-        """Yield ``(namespace, mode, data)`` chunks for the active daemon turn."""
+    async def iter_turn_chunks(
+        self,
+        *,
+        max_wait_s: float | None = None,
+    ) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
+        """Yield ``(namespace, mode, data)`` chunks for the active daemon turn.
+
+        Args:
+            max_wait_s: Optional absolute deadline for the whole turn. When set,
+                raises ``TimeoutError`` if the daemon never emits a turn-end
+                signal in time (idle after payload, stopped, stream.end, or
+                strange_loop.completed).
+        """
         self.turn_event_stats = self._new_turn_stats()
         self.last_turn_end_state = None
         self.last_turn_cancellation_seen = False
@@ -303,6 +320,9 @@ class DaemonSession:
         turn_read_started = time.monotonic()
         first_event_logged = False
         progress_seen = False
+        absolute_deadline = (
+            time.monotonic() + max_wait_s if max_wait_s is not None and max_wait_s > 0 else None
+        )
         peel = getattr(self._client, "peel_stale_pending_control_events", None)
         stale_pending = peel() if callable(peel) else []
         if stale_pending:
@@ -315,6 +335,11 @@ class DaemonSession:
         async with self._read_lock:
             try:
                 while True:
+                    if absolute_deadline is not None and time.monotonic() >= absolute_deadline:
+                        raise TimeoutError(
+                            f"Turn timed out after {max_wait_s:.0f}s "
+                            f"(loop={expected_loop_id or '?'})"
+                        )
                     if not progress_seen and time.monotonic() - turn_read_started > 30.0:
                         logger.warning(
                             "No daemon stream progress after %.0fs (loop=%s, "
@@ -407,7 +432,14 @@ class DaemonSession:
                     if mode == "custom" and isinstance(data, dict):
                         custom_type = str(data.get("type", "")).strip()
                         if custom_type in _TURN_END_CUSTOM_TYPES:
-                            self.last_turn_end_state = "completed"
+                            # stream.end may be scope-tagged; treat blank / turn as end.
+                            if custom_type == "soothe.stream.end":
+                                scope = str(data.get("scope") or "turn").strip().lower()
+                                if scope not in {"", "turn"}:
+                                    continue
+                            self.last_turn_end_state = (
+                                "stream_end" if custom_type == "soothe.stream.end" else "completed"
+                            )
                             async for chunk in self._drain_stream_events_after_idle(
                                 expected_loop_id=expected_loop_id,
                             ):

soothe_client/appkit/managed_client.py

@@ -1,7 +1,7 @@
-"""ManagedClient seam for appkit ConnectionPool / TurnRunner (RFC-629).
+"""ManagedClient adapter used by ConnectionPool and TurnRunner.
 
-The concrete ``WebSocketClient`` satisfies it via ``WebSocketManagedClient``;
-tests supply fakes.
+Wraps ``WebSocketClient`` and upgrades flat appkit payloads
+(``loop_input``, ``command_request``, …) to protocol-1 envelopes before send.
 """
 
 from __future__ import annotations
@@ -18,10 +18,72 @@ BootstrapFunc = Callable[
     Awaitable[str],
 ]
 
+# Flat appkit payloads still use legacy ``{"type": "<op>", ...}`` maps (parity
+# with Go InputMessageForLoop). The live daemon accepts protocol-1 envelopes
+# only — coerce at the ManagedClient boundary before send.
+_ALREADY_ENVELOPE_TYPES = frozenset(
+    {
+        "request",
+        "response",
+        "notification",
+        "subscribe",
+        "next",
+        "error",
+        "complete",
+        "unsubscribe",
+        "connection_init",
+        "connection_ack",
+        "ping",
+        "pong",
+        "receipt_response",
+    }
+)
+_NOTIFICATION_METHODS = frozenset({"loop_input", "slash_command", "disconnect", "delivery_ack"})
+_REQUEST_METHOD_ALIASES = {
+    # TurnRunner cancel uses flat command_request; wire method is rpc_command.
+    "command_request": "rpc_command",
+}
+
+
+def _coerce_appkit_wire_message(msg: dict[str, Any], client: WebSocketClient) -> dict[str, Any]:
+    """Upgrade flat appkit dicts to protocol-1 envelopes when needed."""
+    from soothe_sdk.wire.codec import MessageType, WireEnvelope
+
+    msg_type = str(msg.get("type") or "")
+    if msg.get("proto") == "1" or msg_type in _ALREADY_ENVELOPE_TYPES:
+        return msg
+
+    params = {
+        key: value
+        for key, value in msg.items()
+        if key not in {"type", "proto", "method", "params", "id", "request_id"}
+    }
+
+    if msg_type in _NOTIFICATION_METHODS:
+        return WireEnvelope(
+            proto="1",
+            type=MessageType.NOTIFICATION.value,
+            method=msg_type,
+            params=params,
+        ).to_wire_dict()
+
+    if msg_type in _REQUEST_METHOD_ALIASES or msg_type:
+        request_method = _REQUEST_METHOD_ALIASES.get(msg_type, msg_type)
+        req_id = str(msg.get("request_id") or msg.get("id") or client._next_request_id())
+        return WireEnvelope(
+            proto="1",
+            type=MessageType.REQUEST.value,
+            method=request_method,
+            params=params,
+            id=req_id,
+        ).to_wire_dict()
+
+    return msg
+
 
 @runtime_checkable
 class ManagedClient(Protocol):
-    """Subset of Layer 0 that ConnectionPool and TurnRunner depend on."""
+    """Subset of WebSocketClient that ConnectionPool and TurnRunner depend on."""
 
     async def connect(self) -> None:
         """Dial and handshake."""
@@ -72,7 +134,7 @@ class WebSocketManagedClient:
 
     @property
     def underlying(self) -> WebSocketClient:
-        """Return the wrapped Layer 0 client."""
+        """Return the wrapped WebSocketClient."""
         return self._client
 
     async def connect(self) -> None:
@@ -89,7 +151,7 @@ class WebSocketManagedClient:
     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)
+        await self._client.send(_coerce_appkit_wire_message(msg, self._client))
 
     async def receive_messages(
         self,

soothe_client/appkit/pool.py

@@ -1,4 +1,4 @@
-"""Per-session connection pool for appkit (RFC-629 Layer 1).
+"""Per-session connection pool for appkit.
 
 Manages a pool of daemon connections, one active per session. Reuses an
 active connection when still live, otherwise bootstraps a fresh loop or

soothe_client/appkit/query_gate.py

@@ -1,4 +1,4 @@
-"""Single-flight query gate (RFC-629 Layer 1)."""
+"""Single-flight query gate."""
 
 from __future__ import annotations
 

soothe_client/appkit/session_store.py

@@ -1,4 +1,4 @@
-"""Persistence seam for appkit (RFC-629 Layer 1)."""
+"""Persistence seam for appkit."""
 
 from __future__ import annotations
 

soothe_client/appkit/thinking_step.py

@@ -1,4 +1,4 @@
-"""Thinking-step extraction for appkit (RFC-629 Layer 1).
+"""Thinking-step extraction for appkit.
 
 Maps an allowlisted progress event to one structured UI line. Free-form
 streams (tokens, reports, reasoning) are excluded. Ported from Go/TS appkit.

soothe_client/appkit/turn_runner.py

@@ -1,11 +1,11 @@
-"""Turn runner for appkit (RFC-629 Layer 1).
+"""Turn runner for appkit.
 
 Executes one query turn end-to-end: acquire a pooled connection, enforce
 single-flight, send loop_input, consume the event stream, classify events,
 resolve the deliverable, persist the reply, and broadcast completion.
 
 Supports absolute query timeout, optional idle silence watchdog, soft-complete
-policies (IG-651), and optional attachment compaction before send.
+policies, and optional attachment compaction before send.
 """
 
 from __future__ import annotations

soothe_client/helpers.py

@@ -5,36 +5,35 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from typing import Any
 
+from soothe_sdk.wire.codec import ProtocolError
+
 from soothe_client.websocket import WebSocketClient
 
 logger = logging.getLogger(__name__)
 
 
 def websocket_url_from_config(cfg: Any) -> str:
-    """Construct WebSocket URL from a config-like object.
-
-    Duck-typed across the three workspace configs:
+    """Build a WebSocket URL from a config-like object.
 
-    * ``CLIConfig`` (`soothe-cli`) exposes ``daemon_host`` / ``daemon_port``
-      and a ``websocket_url()`` helper.
-    * ``SootheDaemonConfig`` (`soothe-daemon`) exposes
-      ``transports.websocket.host`` / ``.port``.
-    * Legacy callers may still pass an object with
-      ``daemon.transports.websocket.host`` / ``.port``.
+    Accepts any object that provides one of:
 
-    The SDK deliberately does not import any of those classes — keeping
-    `soothe_sdk` independent of `soothe`, `soothe_cli`, and `soothe_daemon`.
+    * ``websocket_url()`` callable
+    * ``daemon_host`` / ``daemon_port``
+    * ``transports.websocket.host`` / ``.port``
+    * ``daemon.transports.websocket.host`` / ``.port``
 
     Args:
-        cfg: Any object exposing one of the shapes above.
+        cfg: Config-like object.
 
     Returns:
-        WebSocket URL string (e.g., ``"ws://127.0.0.1:8765"``).
+        WebSocket URL (e.g. ``"ws://127.0.0.1:8765"``).
 
     Raises:
-        AttributeError: If ``cfg`` exposes none of the supported shapes.
+        AttributeError: If none of the supported shapes are present.
     """
     if hasattr(cfg, "websocket_url") and callable(cfg.websocket_url):
         url = cfg.websocket_url()
@@ -62,7 +61,7 @@ def websocket_url_from_config(cfg: Any) -> str:
 
 
 async def _ensure_handshake(client: WebSocketClient, *, timeout: float) -> None:
-    """Complete the protocol-1 readiness handshake when not already done (RFC-450 §8.2).
+    """Complete the protocol-1 readiness handshake when not already done.
 
     Args:
         client: Connected WebSocketClient.
@@ -79,6 +78,80 @@ async def _ensure_handshake(client: WebSocketClient, *, timeout: float) -> None:
     await client.wait_for_connection_ack(ack_timeout_s=timeout)
 
 
+@asynccontextmanager
+async def connected_websocket(
+    ws_url: str,
+    *,
+    timeout: float = 30.0,
+) -> AsyncIterator[WebSocketClient]:
+    """Connect, handshake, and yield a ready ``WebSocketClient``.
+
+    Args:
+        ws_url: Daemon WebSocket URL.
+        timeout: Handshake / overall connect budget in seconds.
+
+    Yields:
+        A connected client with protocol-1 handshake complete.
+    """
+    client = WebSocketClient(url=ws_url)
+    try:
+        await client.connect()
+        await asyncio.wait_for(_ensure_handshake(client, timeout=timeout), timeout=timeout)
+        yield client
+    finally:
+        await client.close()
+
+
+async def protocol1_rpc(
+    ws_url: str,
+    method: str,
+    params: dict[str, Any] | None = None,
+    *,
+    mode: str = "request",
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    """One-shot protocol-1 RPC / notify / subscribe with dict error contract.
+
+    Callers check ``if "error" in response``. Used by Typer commands that do not
+    hold a long-lived session.
+
+    Args:
+        ws_url: WebSocket URL.
+        method: RPC method, notify target, or subscribe channel.
+        params: Structured parameters.
+        mode: ``request``, ``notify``, or ``subscribe``.
+        timeout: Seconds for handshake and the RPC itself.
+
+    Returns:
+        Result dict, ``{}`` for notify, ``{"subscription_id": ...}`` for
+        subscribe, or ``{"error": "..."}`` on failure.
+    """
+    try:
+        async with connected_websocket(ws_url, timeout=timeout) as client:
+            if mode == "notify":
+                await asyncio.wait_for(client.notify(method, params or {}), timeout=timeout)
+                return {}
+            if mode == "subscribe":
+                sub_id = await asyncio.wait_for(
+                    client.subscribe(method, params or {}, timeout=timeout),
+                    timeout=timeout,
+                )
+                return {"subscription_id": sub_id}
+            result = await asyncio.wait_for(
+                client.request(method, params or {}, timeout=timeout),
+                timeout=timeout,
+            )
+            return result if isinstance(result, dict) else {"result": result}
+    except TimeoutError:
+        return {"error": "Timed out waiting for daemon response"}
+    except ProtocolError as exc:
+        return {"error": str(exc)}
+    except (ConnectionError, OSError) as exc:
+        return {"error": f"Connection error: {exc}"}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
 async def check_daemon_status(
     client: WebSocketClient,
     timeout: float = 5.0,
@@ -115,7 +188,7 @@ async def check_daemon_status(
 def _daemon_status_indicates_live(status: dict) -> bool:
     """Infer liveness from a ``daemon_status`` response payload.
 
-    Uses ``readiness_state`` (RFC-450 §8.2): transitional states (``starting``,
+    Uses ``readiness_state``: transitional states (``starting``,
     ``warming``) mean the daemon is not yet ready for loops; terminal states
     (``error``, ``degraded``, ``stopped``) mean it cannot serve loops; only
     ``ready`` is live for loop operations.
@@ -142,7 +215,7 @@ async def is_daemon_live(
 ) -> bool:
     """Composite health check: connection + status RPC.
 
-    Optionally waits for daemon to reach "ready" state (IG-489), polling during
+    Optionally waits for daemon to reach "ready" state, polling during
     transitional states like "starting" and "warming".
 
     Args:
@@ -317,7 +390,7 @@ async def fetch_config_section(client: WebSocketClient, section: str, timeout: f
     """Fetch daemon config section via RPC.
 
     Performs ``connection_init`` / ``connection_ack`` handshake when needed
-    before sending the request (RFC-450 §8.2).
+    before sending the request.
 
     Args:
         client: Connected WebSocketClient
@@ -392,6 +465,8 @@ async def fetch_loop_messages(
 
 __all__ = [
     "websocket_url_from_config",
+    "connected_websocket",
+    "protocol1_rpc",
     "check_daemon_status",
     "is_daemon_live",
     "request_daemon_shutdown",