soothe-client-python 1.0.8__tar.gz → 1.0.10__tar.gz

{soothe_client_python-1.0.8 → soothe_client_python-1.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soothe-client-python
-Version: 1.0.8
+Version: 1.0.10
 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.8 → soothe_client_python-1.0.10}/src/soothe_client/appkit/daemon_session.py

@@ -24,7 +24,14 @@ from soothe_client.stream_terminal import (
     is_turn_end_custom_data,
     is_turn_progress_chunk,
 )
-from soothe_client.turn_boundary import frame_seq, frame_turn_id, parse_turn_generation
+from soothe_client.turn_boundary import (
+    frame_seq,
+    frame_turn_id,
+    is_idle_terminal_allowed,
+    is_turn_terminal_allowed,
+    parse_turn_generation,
+    turn_ids_match,
+)
 from soothe_client.websocket import WebSocketClient
 
 logger = logging.getLogger(__name__)
@@ -368,7 +375,6 @@ class DaemonSession:
         # Bind turn_id only after this turn's status=running (do not reuse prior).
         self._expected_turn_id = None
         expected_turn_id: str | None = None
-        stream_payload_seen = False
         turn_progress_seen = False
         last_end_seq = int(getattr(self, "_last_turn_end_seq", 0) or 0)
         self._last_turn_end_seq = last_end_seq
@@ -439,23 +445,37 @@ class DaemonSession:
                     if ev_seq is not None and last_end_seq > 0 and ev_seq <= last_end_seq:
                         continue
 
-                    # Drop mismatched turn_id once bound — except status=running,
-                    # which may rebind to a newer generation (pre-admit early
-                    # running can briefly carry a stale or empty turn_id).
+                    # Once bound, drop absent/mismatched turn_id on event/status
+                    # (except status=running, which may rebind to a newer gen;
+                    # pre-admit early running can omit turn_id). Idle/stopped
+                    # fall through to their gates (cancel idle may omit turn_id).
                     ev_turn_id = frame_turn_id(event)
-                    is_running_status = (
-                        event_type == "status" and str(event.get("state") or "") == "running"
-                    )
+                    status_state = str(event.get("state") or "") if event_type == "status" else ""
+                    is_running_status = status_state == "running"
+                    is_terminal_status = status_state in {"idle", "stopped"}
                     if (
                         expected_turn_id
-                        and ev_turn_id
-                        and ev_turn_id != expected_turn_id
                         and event_type in {"event", "status"}
                         and not is_running_status
+                        and not is_terminal_status
+                        and not turn_ids_match(expected_turn_id, ev_turn_id)
                     ):
                         logger.debug(
-                            "Ignoring mismatched turn_id frame type=%s got=%s expected=%s",
+                            "Ignoring unbound/mismatched turn_id frame type=%s got=%s expected=%s",
                             event_type,
+                            (ev_turn_id or "<absent>")[-24:],
+                            expected_turn_id[-24:],
+                        )
+                        continue
+                    if (
+                        expected_turn_id
+                        and is_terminal_status
+                        and ev_turn_id
+                        and not turn_ids_match(expected_turn_id, ev_turn_id)
+                    ):
+                        logger.debug(
+                            "Ignoring mismatched terminal status=%s got=%s expected=%s",
+                            status_state,
                             ev_turn_id[-24:],
                             expected_turn_id[-24:],
                         )
@@ -478,6 +498,9 @@ class DaemonSession:
                             query_started = True
                             progress_seen = True
                             status_turn = frame_turn_id(event)
+                            # Bind only from running frames that carry turn_id.
+                            # Pre-admit early running omits turn_id and must not
+                            # unlock terminals or poison the expected id.
                             if status_turn:
                                 new_gen = parse_turn_generation(status_turn)
                                 old_gen = parse_turn_generation(expected_turn_id)
@@ -487,11 +510,13 @@ class DaemonSession:
                                     if expected_turn_id and status_turn != expected_turn_id:
                                         # Successor turn admitted while this reader
                                         # still held a stale/early binding.
-                                        stream_payload_seen = False
                                         turn_progress_seen = False
                                     expected_turn_id = status_turn
                                     self._expected_turn_id = status_turn
                         elif query_started and state == "stopped":
+                            stop_turn = frame_turn_id(event)
+                            if expected_turn_id and not turn_ids_match(expected_turn_id, stop_turn):
+                                continue
                             self.last_turn_end_state = state
                             if ev_seq is not None:
                                 self._last_turn_end_seq = max(self._last_turn_end_seq, ev_seq)
@@ -501,7 +526,22 @@ class DaemonSession:
                                 yield chunk
                             break
                         elif query_started and state == "idle":
-                            if not stream_payload_seen and not self.last_turn_cancellation_seen:
+                            idle_turn = frame_turn_id(event)
+                            if not is_idle_terminal_allowed(
+                                expected_turn_id=expected_turn_id,
+                                frame_turn_id=idle_turn,
+                                query_started=query_started,
+                                turn_progress_seen=turn_progress_seen,
+                                cancellation_seen=self.last_turn_cancellation_seen,
+                            ):
+                                logger.debug(
+                                    "Ignoring premature idle "
+                                    "(loop=%s bound=%s idle_turn=%s progress=%s)",
+                                    (expected_loop_id or "?")[:16],
+                                    bool(expected_turn_id),
+                                    (idle_turn or "<absent>")[-24:],
+                                    turn_progress_seen,
+                                )
                                 continue
                             self.last_turn_end_state = state
                             if ev_seq is not None:
@@ -529,30 +569,34 @@ class DaemonSession:
                         self.turn_event_stats.filtered_early += 1
                         continue
 
-                    # Prefer turn_id match when present; else IG-615 progress gate.
+                    # Strict turn_id match: absent ids never unlock turn-end.
                     if mode == "custom" and is_turn_end_custom_data(data):
                         data_turn = (
                             frame_turn_id(data if isinstance(data, dict) else None) or ev_turn_id
                         )
-                        turn_ok = (
-                            not expected_turn_id or not data_turn or data_turn == expected_turn_id
+                        turn_ok = is_turn_terminal_allowed(
+                            expected_turn_id=expected_turn_id,
+                            frame_turn_id=data_turn,
+                            query_started=query_started,
+                            turn_progress_seen=turn_progress_seen,
                         )
-                        if not turn_ok or not query_started or not turn_progress_seen:
+                        if not turn_ok:
                             logger.debug(
                                 "Ignoring premature turn-end frame %s "
-                                "(loop=%s query_started=%s progress=%s turn_ok=%s)",
+                                "(loop=%s query_started=%s progress=%s "
+                                "bound=%s data_turn=%s)",
                                 str(data.get("type", "")).strip()
                                 if isinstance(data, dict)
                                 else "?",
                                 (expected_loop_id or "?")[:16],
                                 query_started,
                                 turn_progress_seen,
-                                turn_ok,
+                                bool(expected_turn_id),
+                                (data_turn or "<absent>")[-24:],
                             )
                             continue
 
                     progress_seen = True
-                    stream_payload_seen = True
                     if is_turn_progress_chunk(mode, data):
                         turn_progress_seen = True
                     yield (namespace, mode, data)

{soothe_client_python-1.0.8 → soothe_client_python-1.0.10}/src/soothe_client/appkit/turn_boundary.py

@@ -14,6 +14,13 @@ from soothe_client.stream_terminal import (
     is_turn_end_custom_data,
     is_turn_progress_chunk,
 )
+from soothe_client.turn_boundary import (
+    frame_turn_id,
+    is_idle_terminal_allowed,
+    is_turn_terminal_allowed,
+    parse_turn_generation,
+    turn_ids_match,
+)
 
 TURN_END_STREAM_END = STREAM_END
 TURN_END_IDLE = "status.idle"
@@ -25,8 +32,9 @@ 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
+    expected_turn_id: str | None = None
+    cancellation_seen: bool = False
 
     def observe(self, msg: Any) -> None:
         frame = _normalize_frame(msg)
@@ -36,18 +44,38 @@ class TurnLifecycleGate:
         if typ == "status":
             if str(frame.get("state") or "").strip().lower() == "running":
                 self.saw_running = True
+                status_turn = frame_turn_id(frame)
+                if status_turn:
+                    new_gen = parse_turn_generation(status_turn)
+                    old_gen = parse_turn_generation(self.expected_turn_id)
+                    if self.expected_turn_id is None or (
+                        new_gen is not None and (old_gen is None or new_gen >= old_gen)
+                    ):
+                        if self.expected_turn_id and status_turn != self.expected_turn_id:
+                            self.saw_turn_progress = False
+                        self.expected_turn_id = status_turn
             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_stream_end(self, frame_turn: str | None) -> bool:
+        return is_turn_terminal_allowed(
+            expected_turn_id=self.expected_turn_id,
+            frame_turn_id=frame_turn,
+            query_started=self.saw_running,
+            turn_progress_seen=self.saw_turn_progress,
+        )
 
-    def allow_idle_complete(self) -> bool:
-        return self.saw_running and self.saw_stream_payload
+    def allow_idle_complete(self, frame_turn: str | None) -> bool:
+        return is_idle_terminal_allowed(
+            expected_turn_id=self.expected_turn_id,
+            frame_turn_id=frame_turn,
+            query_started=self.saw_running,
+            turn_progress_seen=self.saw_turn_progress,
+            cancellation_seen=self.cancellation_seen,
+        )
 
 
 @dataclass
@@ -69,16 +97,28 @@ class TurnBoundary:
         typ = str(frame.get("type") or "")
         if typ == "status":
             state = str(frame.get("state") or "").strip().lower()
+            frame_turn = frame_turn_id(frame)
             if state == "stopped" and self.gate.saw_running:
+                if self.gate.expected_turn_id and not turn_ids_match(
+                    self.gate.expected_turn_id, frame_turn
+                ):
+                    return False, ""
                 return self._mark(TURN_END_STOPPED)
-            if state == "idle" and self.gate.allow_idle_complete():
+            if state == "idle" and self.gate.allow_idle_complete(frame_turn):
                 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():
+            data_turn = frame_turn_id(data if isinstance(data, dict) else None) or frame_turn_id(
+                frame
+            )
+            if (
+                mode == "custom"
+                and is_turn_end_custom_data(data)
+                and self.gate.allow_stream_end(data_turn)
+            ):
                 return self._mark(TURN_END_STREAM_END)
         return False, ""
 
@@ -109,19 +149,27 @@ def _normalize_frame(msg: Any) -> dict[str, Any] | None:
         if isinstance(inner, dict) and inner.get("type") == "status":
             return inner
         if isinstance(inner, dict) and inner.get("mode"):
-            return {
+            out = {
                 "type": "event",
                 "mode": inner.get("mode"),
                 "data": inner.get("data"),
                 "namespace": inner.get("namespace") or payload.get("namespace"),
             }
+            tid = inner.get("turn_id") or payload.get("turn_id") or msg.get("turn_id")
+            if tid:
+                out["turn_id"] = tid
+            return out
         mode = payload.get("mode")
         if mode:
-            return {
+            out = {
                 "type": "event",
                 "mode": mode,
                 "data": payload.get("data"),
                 "namespace": payload.get("namespace"),
             }
+            tid = payload.get("turn_id") or msg.get("turn_id")
+            if tid:
+                out["turn_id"] = tid
+            return out
         return None
     return msg

{soothe_client_python-1.0.8 → soothe_client_python-1.0.10}/src/soothe_client/command_client.py

@@ -132,34 +132,6 @@ async def _perform_handshake(ws: Any, *, timeout: float) -> None:
             raise RuntimeError(f"Daemon state is {state}")
 
 
-# Command message types
-_AUTOPilot_COMMANDS = {
-    "status": "autopilot_status",
-    "submit": "autopilot_submit",
-    "list_goals": "autopilot_list_goals",
-    "get_goal": "autopilot_get_goal",
-    "cancel_goal": "autopilot_cancel_goal",
-    "cancel_all": "autopilot_cancel_all",
-    "wake": "autopilot_wake",
-    "dream": "autopilot_dream",
-    "resume": "autopilot_resume",
-    "list_jobs": "autopilot_list_jobs",
-    "get_job": "autopilot_get_job",
-}
-
-_CRON_COMMANDS = {
-    "add": "cron_add",
-    "list": "cron_list",
-    "list_jobs": "cron_list",
-    "show": "cron_show",
-    "cancel": "cron_cancel",
-}
-
-_MEMORY_COMMANDS = {
-    "stats": "memory_stats",
-}
-
-
 class AsyncCommandClient:
     """Async client for one-shot daemon RPCs (jobs, autopilot, cron).
 
@@ -270,12 +242,19 @@ class AsyncCommandClient:
         return await self._send_command("autopilot_status")
 
     async def autopilot_submit(
-        self, description: str, *, priority: int = 50, workspace: str | None = None
+        self,
+        description: str,
+        *,
+        priority: int = 50,
+        workspace: str | None = None,
+        rail_id: str | None = None,
     ) -> dict[str, Any]:
         """Submit a new autopilot goal (returns ``goal_id``)."""
         payload: dict[str, Any] = {"description": description, "priority": priority}
         if workspace:
             payload["workspace"] = workspace
+        if rail_id:
+            payload["rail_id"] = rail_id
         return await self._send_command("autopilot_submit", payload)
 
     async def autopilot_list_goals(self) -> dict[str, Any]:
@@ -318,6 +297,14 @@ class AsyncCommandClient:
         """Get a root job with DAG snapshot. Prefer ``job_status`` / ``job_dag``."""
         return await self._send_command("autopilot_get_job", {"job_id": job_id})
 
+    async def autopilot_top(self, *, include_terminal: bool = False) -> dict[str, Any]:
+        """Jobs → goals → loops snapshot for CLI ``top`` (IG-679 / IG-688).
+
+        Args:
+            include_terminal: When true, include terminal goals and jobs.
+        """
+        return await self._send_command("autopilot_top", {"include_terminal": include_terminal})
+
     async def autopilot_subscribe(self) -> dict[str, Any]:
         """Subscribe this connection to autopilot worker events."""
         return await self._send_command("autopilot_subscribe")
@@ -442,13 +429,23 @@ class CommandClient:
         return cast(dict[str, Any], self._run_async(self._client.autopilot_status()))
 
     def autopilot_submit(
-        self, description: str, *, priority: int = 50, workspace: str | None = None
+        self,
+        description: str,
+        *,
+        priority: int = 50,
+        workspace: str | None = None,
+        rail_id: str | None = None,
     ) -> dict[str, Any]:
         """Submit a new autopilot goal."""
         return cast(
             dict[str, Any],
             self._run_async(
-                self._client.autopilot_submit(description, priority=priority, workspace=workspace)
+                self._client.autopilot_submit(
+                    description,
+                    priority=priority,
+                    workspace=workspace,
+                    rail_id=rail_id,
+                )
             ),
         )
 
@@ -488,6 +485,13 @@ class CommandClient:
         """Get a root job with DAG snapshot."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_get_job(job_id)))
 
+    def autopilot_top(self, *, include_terminal: bool = False) -> dict[str, Any]:
+        """Jobs → goals → loops snapshot for CLI ``top``."""
+        return cast(
+            dict[str, Any],
+            self._run_async(self._client.autopilot_top(include_terminal=include_terminal)),
+        )
+
     def autopilot_subscribe(self) -> dict[str, Any]:
         """Subscribe to autopilot worker events."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_subscribe()))

{soothe_client_python-1.0.8 → soothe_client_python-1.0.10}/src/soothe_client/protocol_params.py

@@ -38,6 +38,7 @@ __all__ = [
     "AutopilotResumeParams",
     "AutopilotListJobsParams",
     "AutopilotGetJobParams",
+    "AutopilotTopParams",
     # Job RPC params
     "JobCreateParams",
     "JobStatusParams",
@@ -401,6 +402,16 @@ class AutopilotGetJobParams(ParamsBase):
     job_id: str = Field(..., min_length=1)
 
 
+class AutopilotTopParams(ParamsBase):
+    """Params for ``method=autopilot_top`` (IG-679 / IG-688).
+
+    Attributes:
+        include_terminal: Include terminal goals/jobs when true (default false).
+    """
+
+    include_terminal: bool = False
+
+
 # ---------------------------------------------------------------------------
 # Job RPC params
 # ---------------------------------------------------------------------------

{soothe_client_python-1.0.8 → soothe_client_python-1.0.10}/src/soothe_client/turn_boundary.py

@@ -61,9 +61,66 @@ def frame_seq(frame: dict[str, Any] | None) -> int | None:
     return None
 
 
+def turn_ids_match(expected: str | None, candidate: str | None) -> bool:
+    """True when both ids are non-empty and equal.
+
+    Absent ids never match — callers must not treat missing ``turn_id`` as
+    compatible with a bound turn (prior-goal terminals / idle can omit or
+    carry a stale generation).
+    """
+    exp = str(expected or "").strip()
+    cand = str(candidate or "").strip()
+    return bool(exp) and bool(cand) and exp == cand
+
+
+def is_turn_terminal_allowed(
+    *,
+    expected_turn_id: str | None,
+    frame_turn_id: str | None,
+    query_started: bool,
+    turn_progress_seen: bool,
+) -> bool:
+    """Gate for turn-scoped ``stream.end`` / ``strange_loop.completed``.
+
+    Requires an active query, real turn progress, a bound ``expected_turn_id``,
+    and an exact ``frame_turn_id`` match. Absent ids are rejected.
+    """
+    if not query_started or not turn_progress_seen:
+        return False
+    return turn_ids_match(expected_turn_id, frame_turn_id)
+
+
+def is_idle_terminal_allowed(
+    *,
+    expected_turn_id: str | None,
+    frame_turn_id: str | None,
+    query_started: bool,
+    turn_progress_seen: bool,
+    cancellation_seen: bool = False,
+) -> bool:
+    """Gate for ``status=idle`` soft-complete.
+
+    Requires a bound turn. Matching ``turn_id`` needs progress or cancel.
+    Absent idle ``turn_id`` is allowed only when cancellation was already seen
+    (legacy cancel finalize); mismatched ids are always rejected.
+    """
+    if not query_started or not str(expected_turn_id or "").strip():
+        return False
+    cand = str(frame_turn_id or "").strip()
+    if cand:
+        if not turn_ids_match(expected_turn_id, cand):
+            return False
+        return bool(turn_progress_seen or cancellation_seen)
+    # Absent idle turn_id: never end a healthy turn; cancel path only.
+    return bool(cancellation_seen)
+
+
 __all__ = [
     "format_turn_id",
     "frame_seq",
     "frame_turn_id",
+    "is_idle_terminal_allowed",
+    "is_turn_terminal_allowed",
     "parse_turn_generation",
+    "turn_ids_match",
 ]