soothe-client-python 1.0.1__tar.gz → 1.0.2__tar.gz

{soothe_client_python-1.0.1 → soothe_client_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soothe-client-python
-Version: 1.0.1
+Version: 1.0.2
 Summary: WebSocket client + appkit for soothe-daemon (Python)
 Project-URL: Homepage, https://github.com/mirasoth/soothe-client-python
 Project-URL: Documentation, https://soothe.readthedocs.io

{soothe_client_python-1.0.1 → soothe_client_python-1.0.2}/src/soothe_client/appkit/__init__.py

@@ -42,6 +42,14 @@ from soothe_client.appkit.thinking_step import (
     DEFAULT_THINKING_STEP_EVENTS,
     extract_thinking_step,
 )
+from soothe_client.appkit.turn_boundary import (
+    TURN_END_IDLE,
+    TURN_END_STOPPED,
+    TURN_END_STREAM_END,
+    TurnBoundary,
+    TurnLifecycleGate,
+    is_daemon_turn_end_event,
+)
 from soothe_client.appkit.turn_runner import (
     STREAM_CLOSE_FAIL,
     STREAM_CLOSE_SOFT_COMPLETE,
@@ -88,10 +96,16 @@ __all__ = [
     "SessionMessage",
     "SessionStore",
     "StreamClosePolicy",
+    "TURN_END_IDLE",
+    "TURN_END_STOPPED",
+    "TURN_END_STREAM_END",
     "TimeoutPolicy",
+    "TurnBoundary",
     "TurnConfig",
+    "TurnLifecycleGate",
     "TurnRunner",
     "compact_attachments",
+    "is_daemon_turn_end_event",
     "compact_image_attachment",
     "default_pool_config",
     "extract_thinking_step",

{soothe_client_python-1.0.1 → soothe_client_python-1.0.2}/src/soothe_client/appkit/classifier.py

@@ -49,9 +49,9 @@ class ClassifierConfig:
             persisted as final (avoids finishing on stub ACKs). Defaults to 8.
         thinking_step_events: Optional override of the default thinking-step
             event allowlist.
-        treat_status_idle_as_complete: When true, a status frame with
-            ``state==idle`` and non-empty accumulated assistant text completes
-            the turn (typical for intent-hint turns). Default false.
+        treat_status_idle_as_complete: Standalone ``classify`` only. Prefer
+            ``TurnRunner`` + ``TurnBoundary`` for turn end (DaemonSession
+            contract). Default false.
     """
 
     deliverable_phases: frozenset[str] | set[str]
@@ -85,6 +85,8 @@ class EventClassifier:
             return False
         if event_type in (
             "status.idle",
+            "status.stopped",
+            "soothe.stream.end",
             "idle_timeout",
             "query_timeout",
             "stream_closed",

soothe_client_python-1.0.2/src/soothe_client/appkit/turn_boundary.py

@@ -0,0 +1,127 @@
+"""DaemonSession turn-end contract for the pool TurnRunner path.
+
+TurnRunner owns one ``TurnBoundary`` per Execute. EventClassifier may
+early-complete on deliverable phases for UX; it is not the sole terminator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from soothe_client.stream_terminal import (
+    STREAM_END,
+    is_turn_end_custom_data,
+    is_turn_progress_chunk,
+)
+
+TURN_END_STREAM_END = STREAM_END
+TURN_END_IDLE = "status.idle"
+TURN_END_STOPPED = "status.stopped"
+
+
+@dataclass
+class TurnLifecycleGate:
+    """Per-turn progress flags (DaemonSession parity; not shared across chats)."""
+
+    saw_running: bool = False
+    saw_stream_payload: bool = False
+    saw_turn_progress: bool = False
+
+    def observe(self, msg: Any) -> None:
+        frame = _normalize_frame(msg)
+        if frame is None:
+            return
+        typ = str(frame.get("type") or "")
+        if typ == "status":
+            if str(frame.get("state") or "").strip().lower() == "running":
+                self.saw_running = True
+            return
+        if typ == "event":
+            self.saw_stream_payload = True
+            mode = str(frame.get("mode") or "")
+            if is_turn_progress_chunk(mode, frame.get("data")):
+                self.saw_turn_progress = True
+
+    def allow_stream_end(self) -> bool:
+        return self.saw_running and self.saw_turn_progress
+
+    def allow_idle_complete(self) -> bool:
+        return self.saw_running and self.saw_stream_payload
+
+
+@dataclass
+class TurnBoundary:
+    """Applies DaemonSession end rules to pool decoded frames."""
+
+    gate: TurnLifecycleGate = field(default_factory=TurnLifecycleGate)
+    ended: bool = False
+    reason: str = ""
+
+    def feed(self, msg: Any) -> tuple[bool, str]:
+        if self.ended:
+            return True, self.reason
+        self.gate.observe(msg)
+        frame = _normalize_frame(msg)
+        if frame is None:
+            return False, ""
+
+        typ = str(frame.get("type") or "")
+        if typ == "status":
+            state = str(frame.get("state") or "").strip().lower()
+            if state == "stopped" and self.gate.saw_running:
+                return self._mark(TURN_END_STOPPED)
+            if state == "idle" and self.gate.allow_idle_complete():
+                return self._mark(TURN_END_IDLE)
+            return False, ""
+
+        if typ == "event":
+            mode = str(frame.get("mode") or "")
+            data = frame.get("data")
+            if mode == "custom" and is_turn_end_custom_data(data) and self.gate.allow_stream_end():
+                return self._mark(TURN_END_STREAM_END)
+        return False, ""
+
+    def _mark(self, reason: str) -> tuple[bool, str]:
+        self.ended = True
+        self.reason = reason
+        return True, reason
+
+
+def is_daemon_turn_end_event(completion_event: str) -> bool:
+    """True for TurnBoundary completion_event values (not phase deliverables)."""
+    return (completion_event or "").strip() in {
+        TURN_END_STREAM_END,
+        TURN_END_IDLE,
+        TURN_END_STOPPED,
+    }
+
+
+def _normalize_frame(msg: Any) -> dict[str, Any] | None:
+    if not isinstance(msg, dict):
+        return None
+    typ = msg.get("type")
+    if typ == "next":
+        payload = msg.get("payload")
+        if not isinstance(payload, dict):
+            return None
+        inner = payload.get("data")
+        if isinstance(inner, dict) and inner.get("type") == "status":
+            return inner
+        if isinstance(inner, dict) and inner.get("mode"):
+            return {
+                "type": "event",
+                "mode": inner.get("mode"),
+                "data": inner.get("data"),
+                "namespace": inner.get("namespace") or payload.get("namespace"),
+            }
+        mode = payload.get("mode")
+        if mode:
+            return {
+                "type": "event",
+                "mode": mode,
+                "data": payload.get("data"),
+                "namespace": payload.get("namespace"),
+            }
+        return None
+    return msg

{soothe_client_python-1.0.1 → soothe_client_python-1.0.2}/src/soothe_client/appkit/turn_runner.py

@@ -1,11 +1,11 @@
 """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.
+single-flight, send loop_input, consume the event stream, persist/broadcast.
 
-Supports absolute query timeout, optional idle silence watchdog, soft-complete
-policies, and optional attachment compaction before send.
+Turn end is owned by ``TurnBoundary`` (DaemonSession.iter_turn_chunks contract:
+gated ``stream.end`` / idle / stopped). ``EventClassifier`` selects user-visible
+text and may early-complete on deliverable phases for UX.
 """
 
 from __future__ import annotations
@@ -24,6 +24,7 @@ from soothe_client.appkit.classifier import ChatEventTerminal, EventClassifier
 from soothe_client.appkit.pool import ConnectionPool, PooledConn
 from soothe_client.appkit.query_gate import QueryGate
 from soothe_client.appkit.session_store import SessionMessage, SessionStore
+from soothe_client.appkit.turn_boundary import TurnBoundary, is_daemon_turn_end_event
 from soothe_client.intent_hints import validate_loop_input_intent_hint
 
 Attachment = dict[str, Any]
@@ -261,6 +262,7 @@ class TurnRunner:
 
             assistant_content = ""
             started_at = time.time()
+            boundary = TurnBoundary()
             agen = event_stream.__aiter__()
             arm_idle()
 
@@ -378,6 +380,7 @@ class TurnRunner:
 
                 arm_idle()
 
+                ended, end_reason = boundary.feed(msg)
                 event_result = self._classifier.classify(msg, assistant_content)
                 if (
                     event_result.err is not None
@@ -404,7 +407,9 @@ class TurnRunner:
                     event_result,
                     assistant_content,
                 )
-                if deliverable:
+                if deliverable and not is_daemon_turn_end_event(
+                    event_result.completion_event or ""
+                ):
                     await self._complete_turn(
                         session_id,
                         loop_id,
@@ -413,6 +418,20 @@ class TurnRunner:
                         event_result.completion_event or "",
                     )
                     return
+
+                if ended:
+                    if self._classifier.is_substantive_assistant_reply(assistant_content):
+                        await self._complete_turn(
+                            session_id,
+                            loop_id,
+                            assistant_content.strip(),
+                            started_at,
+                            end_reason,
+                        )
+                        return
+                    empty = RuntimeError(f"turn ended ({end_reason}) with no assistant content")
+                    await self._fail_turn(session_id, loop_id, empty)
+                    raise empty
         finally:
             query_timer.cancel()
             with contextlib.suppress(asyncio.CancelledError):