soothe-client-python 0.9.4__py3-none-any.whl → 0.9.7__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
@@ -155,13 +155,12 @@ class EventClassifier:
             return ChatEventResult(terminal=ChatEventTerminal.CONTINUE)
 
         if typ == "error":
-            err_obj = msg.get("error") if isinstance(msg.get("error"), dict) else {}
-            code = err_obj.get("code") if isinstance(err_obj.get("code"), int) else -32603
-            message = (
-                err_obj.get("message")
-                if isinstance(err_obj.get("message"), str)
-                else "daemon error"
-            )
+            raw_err = msg.get("error")
+            err_obj: dict[str, Any] = raw_err if isinstance(raw_err, dict) else {}
+            raw_code = err_obj.get("code")
+            code = raw_code if isinstance(raw_code, int) else -32603
+            raw_message = err_obj.get("message")
+            message = raw_message if isinstance(raw_message, str) else "daemon error"
             return self._failed_result(DaemonError(code, message, err_obj.get("data")))
 
         if typ == "event":
@@ -174,8 +173,10 @@ class EventClassifier:
         return ChatEventResult(terminal=ChatEventTerminal.CONTINUE)
 
     def _classify_next_envelope(self, env: dict[str, Any]) -> ChatEventResult:
-        payload = env.get("payload") if isinstance(env.get("payload"), dict) else {}
-        inner_data = payload.get("data") if isinstance(payload.get("data"), dict) else None
+        raw_payload = env.get("payload")
+        payload: dict[str, Any] = raw_payload if isinstance(raw_payload, dict) else {}
+        raw_inner = payload.get("data")
+        inner_data: dict[str, Any] | None = raw_inner if isinstance(raw_inner, dict) else None
         if inner_data is not None:
             inner_mode = str(inner_data.get("mode") or "")
             if inner_mode:
@@ -372,8 +373,10 @@ def _first_message_payload(data: Any) -> tuple[str, str, str, bool]:
     msg_map = data[0]
     if not isinstance(msg_map, dict):
         return "", "", "", False
-    msg_type = msg_map.get("type") if isinstance(msg_map.get("type"), str) else ""
-    phase = msg_map.get("phase") if isinstance(msg_map.get("phase"), str) else ""
+    type_raw = msg_map.get("type")
+    msg_type = type_raw if isinstance(type_raw, str) else ""
+    phase_raw = msg_map.get("phase")
+    phase = phase_raw if isinstance(phase_raw, str) else ""
     content = _extract_content_from_message(msg_map)
     return msg_type, content, phase, True
 
@@ -388,7 +391,8 @@ def _loop_ai_message(data: Any) -> dict[str, str] | None:
     phase = phase_raw.strip() if isinstance(phase_raw, str) else ""
     if not phase:
         return None
-    msg_type = msg_map.get("type") if isinstance(msg_map.get("type"), str) else ""
+    type_raw = msg_map.get("type")
+    msg_type = type_raw if isinstance(type_raw, str) else ""
     content = _extract_content_from_message(msg_map)
     return {"type": msg_type, "content": content, "phase": phase}
 

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
@@ -19,13 +18,13 @@ from soothe_client.appkit.chunk_filter import should_drop_stream_chunk_early
 from soothe_client.appkit.events import unwrap_next
 from soothe_client.appkit.observability import TurnEventStats
 from soothe_client.session import bootstrap_loop_session, connect_websocket_with_retries
+from soothe_client.stream_terminal import STREAM_END, is_turn_end_custom_data
 from soothe_client.websocket import WebSocketClient
 
 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"})
 
 EarlyDropFn = Callable[[tuple[Any, ...], str, Any], bool]
 StatsFactory = Callable[[], Any]
@@ -210,6 +209,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 +227,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 +290,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 +315,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 +330,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, "
@@ -401,18 +421,30 @@ class DaemonSession:
                     if self._should_drop(namespace, mode, data):
                         self.turn_event_stats.filtered_early += 1
                         continue
+
+                    # Prior-goal terminal frames can arrive before status=running
+                    # for the new turn; ignoring them prevents a blank second query.
+                    if mode == "custom" and is_turn_end_custom_data(data) and not query_started:
+                        logger.debug(
+                            "Ignoring pre-start turn-end frame %s (loop=%s)",
+                            str(data.get("type", "")).strip(),
+                            (expected_loop_id or "?")[:16],
+                        )
+                        continue
+
                     progress_seen = True
                     stream_payload_seen = True
                     yield (namespace, mode, data)
-                    if mode == "custom" and isinstance(data, dict):
+                    if mode == "custom" and is_turn_end_custom_data(data):
                         custom_type = str(data.get("type", "")).strip()
-                        if custom_type in _TURN_END_CUSTOM_TYPES:
-                            self.last_turn_end_state = "completed"
-                            async for chunk in self._drain_stream_events_after_idle(
-                                expected_loop_id=expected_loop_id,
-                            ):
-                                yield chunk
-                            break
+                        self.last_turn_end_state = (
+                            "stream_end" if custom_type == STREAM_END else "completed"
+                        )
+                        async for chunk in self._drain_stream_events_after_idle(
+                            expected_loop_id=expected_loop_id,
+                        ):
+                            yield chunk
+                        break
                     if mode == "updates" and isinstance(data, dict) and "__interrupt__" in data:
                         continue
             except Exception as exc:

soothe_client/appkit/managed_client.py

@@ -1,13 +1,13 @@
-"""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
 
 from collections.abc import AsyncIterator, Awaitable, Callable
-from typing import Any, Protocol, runtime_checkable
+from typing import Any, Protocol, cast, runtime_checkable
 
 from soothe_client.errors import DisconnectCause
 from soothe_client.websocket import WebSocketClient
@@ -18,10 +18,78 @@ 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 cast(
+            dict[str, Any],
+            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 cast(
+            dict[str, Any],
+            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 +140,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 +157,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
@@ -241,23 +241,23 @@ class TurnRunner:
             input_msg = self._build_input(message, loop_id, atts, opts)
             try:
                 await conn.client.send_message(input_msg)
-            except Exception as err:
-                await self._persist_failed(session_id, loop_id, err)
-                self._broadcast_error(session_id, err)
+            except Exception as send_err:
+                await self._persist_failed(session_id, loop_id, send_err)
+                self._broadcast_error(session_id, send_err)
                 if self._on_error is not None:
-                    self._on_error(session_id, loop_id, err)
+                    self._on_error(session_id, loop_id, send_err)
                 raise
 
             event_stream = conn.event_stream
             if event_stream is None:
-                err = RuntimeError(
+                missing = RuntimeError(
                     f"missing event stream for session {session_id} (loop {loop_id})"
                 )
-                await self._persist_failed(session_id, loop_id, err)
-                self._broadcast_error(session_id, err)
+                await self._persist_failed(session_id, loop_id, missing)
+                self._broadcast_error(session_id, missing)
                 if self._on_error is not None:
-                    self._on_error(session_id, loop_id, err)
-                raise err
+                    self._on_error(session_id, loop_id, missing)
+                raise missing
 
             assistant_content = ""
             started_at = time.time()
@@ -266,9 +266,9 @@ class TurnRunner:
 
             while True:
                 if cancel_event is not None and cancel_event.is_set():
-                    err = RuntimeError("aborted")
-                    await self._fail_turn(session_id, loop_id, err)
-                    raise err
+                    aborted = RuntimeError("aborted")
+                    await self._fail_turn(session_id, loop_id, aborted)
+                    raise aborted
 
                 if query_timed_out.is_set():
                     with contextlib.suppress(Exception):
@@ -298,7 +298,10 @@ class TurnRunner:
                     )
                     return
 
-                next_task = asyncio.create_task(agen.__anext__())
+                async def _pull_next() -> Any:
+                    return await agen.__anext__()
+
+                next_task: asyncio.Task[Any] = asyncio.create_task(_pull_next())
                 waiters: list[asyncio.Task[Any]] = [
                     next_task,
                     asyncio.create_task(query_timed_out.wait()),
@@ -350,9 +353,9 @@ class TurnRunner:
                     return
 
                 if caller_wait is not None and caller_wait in done:
-                    err = RuntimeError("aborted")
-                    await self._fail_turn(session_id, loop_id, err)
-                    raise err
+                    aborted = RuntimeError("aborted")
+                    await self._fail_turn(session_id, loop_id, aborted)
+                    raise aborted
 
                 try:
                     msg = next_task.result()
@@ -369,9 +372,9 @@ class TurnRunner:
                             "stream_closed",
                         )
                         return
-                    err = RuntimeError("event stream closed")
-                    await self._fail_turn(session_id, loop_id, err)
-                    raise err from None
+                    closed = RuntimeError("event stream closed")
+                    await self._fail_turn(session_id, loop_id, closed)
+                    raise closed from None
 
                 arm_idle()