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

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

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

@@ -33,7 +33,7 @@ from soothe_client.helpers import (
     check_daemon_status,
     connected_websocket,
     fetch_config_section,
-    fetch_loop_cards,
+    fetch_execution_state,
     fetch_loop_history,
     fetch_loop_messages,
     fetch_skills_catalog,
@@ -91,8 +91,8 @@ __all__ = [
     "request_daemon_shutdown",
     "fetch_skills_catalog",
     "fetch_config_section",
+    "fetch_execution_state",
     "fetch_loop_history",
-    "fetch_loop_cards",
     "fetch_loop_messages",
     # Intent hints
     "TEXT_COMPLETION",

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/appkit/__init__.py

@@ -7,7 +7,7 @@ Primary building blocks for agent UIs and backends:
 - ``QueryGate`` — one-in-flight query per session
 - ``EventClassifier`` — stream → deliverable mapping
 - ``SSEBroadcaster`` — drop-on-full fan-out to subscribers
-- ``SessionStore`` — persistence seam (Protocol)
+- ``LoopSessionStore`` — persistence seam (Protocol)
 
 Advanced stream/pipeline plumbing lives in submodules
 (``events``, ``chunk_filter``, ``turn``, ``managed_client``).
@@ -21,6 +21,7 @@ from soothe_client.appkit.attachments import (
     compact_image_attachment,
 )
 from soothe_client.appkit.broadcaster import SSEBroadcaster, SSEEvent
+from soothe_client.appkit.card_projection import CardProjection, parse_card_custom_payload
 from soothe_client.appkit.classifier import (
     EVENT_FINAL_REPORT,
     ChatEventResult,
@@ -29,6 +30,11 @@ from soothe_client.appkit.classifier import (
     EventClassifier,
 )
 from soothe_client.appkit.daemon_session import DaemonSession
+from soothe_client.appkit.loop_session_store import (
+    LoopSessionEntry,
+    LoopSessionStore,
+    SessionMessage,
+)
 from soothe_client.appkit.pool import (
     ConnectionPool,
     ErrPoolExhausted,
@@ -37,7 +43,6 @@ from soothe_client.appkit.pool import (
     default_pool_config,
 )
 from soothe_client.appkit.query_gate import ErrQueryBusy, QueryGate
-from soothe_client.appkit.session_store import SessionEntry, SessionMessage, SessionStore
 from soothe_client.appkit.thinking_step import (
     DEFAULT_THINKING_STEP_EVENTS,
     extract_thinking_step,
@@ -72,6 +77,7 @@ __all__ = [
     "STREAM_CLOSE_FAIL",
     "STREAM_CLOSE_SOFT_COMPLETE",
     "Attachment",
+    "CardProjection",
     "ChatEventResult",
     "ChatEventTerminal",
     "ClassifierConfig",
@@ -85,6 +91,8 @@ __all__ = [
     "ErrQueryTimeout",
     "EventClassifier",
     "InputOpts",
+    "LoopSessionEntry",
+    "LoopSessionStore",
     "OnComplete",
     "OnError",
     "PoolConfig",
@@ -92,9 +100,7 @@ __all__ = [
     "QueryGate",
     "SSEBroadcaster",
     "SSEEvent",
-    "SessionEntry",
     "SessionMessage",
-    "SessionStore",
     "StreamClosePolicy",
     "TURN_END_IDLE",
     "TURN_END_STOPPED",
@@ -111,4 +117,5 @@ __all__ = [
     "extract_thinking_step",
     "idle_timeout_for_turn",
     "input_message_for_loop",
+    "parse_card_custom_payload",
 ]

soothe_client_python-1.0.8/src/soothe_client/appkit/card_projection.py

@@ -0,0 +1,10 @@
+"""In-memory apply helpers for daemon ``soothe.card.*`` frames."""
+
+from __future__ import annotations
+
+from soothe_sdk.display.card_wire import CardProjection, parse_card_custom_payload
+
+__all__ = [
+    "CardProjection",
+    "parse_card_custom_payload",
+]

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/appkit/daemon_session.py

@@ -20,6 +20,7 @@ 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_stream_end_cancel_reason,
     is_turn_end_custom_data,
     is_turn_progress_chunk,
 )
@@ -81,6 +82,7 @@ class DaemonSession:
         self.last_turn_end_state: str | None = None
         self.last_turn_cancellation_seen: bool = False
         self.last_turn_error_message: str | None = None
+        self.last_turn_stream_end_reason: str | None = None
         # Last completed turn's seq floor (drop stale prior-turn frames).
         # Scoped to the current peer seq namespace: reset on reconnect / loop
         # change — daemon seq is per-process and restarts after daemon restart.
@@ -359,6 +361,7 @@ class DaemonSession:
         self.last_turn_end_state = None
         self.last_turn_cancellation_seen = False
         self.last_turn_error_message = None
+        self.last_turn_stream_end_reason = None
         inbound_dropped_baseline = getattr(self._client, "inbound_dropped", 0)
         query_started = False
         expected_loop_id = self._loop_id
@@ -431,7 +434,7 @@ class DaemonSession:
                     ):
                         continue
 
-                    # IG-659 phase 5: drop frames at or before prior turn end seq.
+                    # IG-616 phase 5: drop frames at or before prior turn end seq.
                     ev_seq = frame_seq(event)
                     if ev_seq is not None and last_end_seq > 0 and ev_seq <= last_end_seq:
                         continue
@@ -526,7 +529,7 @@ class DaemonSession:
                         self.turn_event_stats.filtered_early += 1
                         continue
 
-                    # Prefer turn_id match when present; else IG-658 progress gate.
+                    # Prefer turn_id match when present; else IG-615 progress gate.
                     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
@@ -555,9 +558,14 @@ class DaemonSession:
                     yield (namespace, mode, data)
                     if mode == "custom" and is_turn_end_custom_data(data):
                         custom_type = str(data.get("type", "")).strip()
-                        self.last_turn_end_state = (
-                            "stream_end" if custom_type == STREAM_END else "completed"
-                        )
+                        if custom_type == STREAM_END:
+                            reason = str(data.get("reason") or "").strip().lower()
+                            self.last_turn_stream_end_reason = reason or None
+                            if is_stream_end_cancel_reason(reason):
+                                self.last_turn_cancellation_seen = True
+                            self.last_turn_end_state = "stream_end"
+                        else:
+                            self.last_turn_end_state = "completed"
                         if ev_seq is not None:
                             self._last_turn_end_seq = max(self._last_turn_end_seq, ev_seq)
                         async for chunk in self._drain_stream_events_after_idle(
@@ -623,40 +631,6 @@ class DaemonSession:
         await self._rpc_client.wait_for_connection_ack(ack_timeout_s=_RPC_HANDSHAKE_TIMEOUT_S)
         self._rpc_connected = True
 
-    async def fetch_loop_cards(self, loop_id: str) -> SimpleNamespace:
-        """Fetch bound display-card snapshot for a loop."""
-        lid = str(loop_id or "").strip()
-        if not lid:
-            return SimpleNamespace(cards=[], seq=0, success=False)
-
-        async with self._rpc_lock:
-            await self._ensure_rpc_connected()
-            try:
-                resp = await self._rpc_client.request(
-                    "loop_cards_fetch",
-                    {"loop_id": lid},
-                    timeout=30.0,
-                )
-            except Exception:
-                logger.warning("loop_cards_fetch failed for loop %s", lid[:16], exc_info=True)
-                return SimpleNamespace(cards=[], seq=0, success=False)
-
-        raw_cards = resp.get("cards")
-        cards = list(raw_cards) if isinstance(raw_cards, list) else []
-        seq = int(resp.get("seq") or 0)
-        context_tokens_raw = resp.get("context_tokens")
-        context_tokens = (
-            context_tokens_raw
-            if isinstance(context_tokens_raw, int) and context_tokens_raw >= 0
-            else 0
-        )
-        return SimpleNamespace(
-            cards=cards,
-            seq=seq,
-            context_tokens=context_tokens,
-            success=True,
-        )
-
     async def fetch_loop_history(self, loop_id: str) -> SimpleNamespace:
         """Fetch goal display snapshots plus live card tail."""
         lid = str(loop_id or "").strip()
@@ -738,27 +712,78 @@ class DaemonSession:
         *,
         timeout: float = 10.0,
         as_node: str | None = None,
-    ) -> None:
-        """Merge partial state into the loop on the daemon host."""
+    ) -> dict[str, Any]:
+        """Merge partial StrangeLoop state via daemon ``loop_state_update``.
+
+        Used by the TUI for interrupt cleanup and token-total persistence.
+        """
         lid = str(loop_id or "").strip()
+        if not lid or not isinstance(values, dict):
+            return {}
+
+        async with self._rpc_lock:
+            await self._ensure_rpc_connected()
+            try:
+                return await self._rpc_client.loop_state_update(
+                    lid,
+                    values,
+                    as_node=as_node,
+                    timeout=timeout,
+                )
+            except Exception:
+                logger.warning("loop_state_update failed for loop %s", lid[:16], exc_info=True)
+                return {}
+
+    async def fetch_execution_state(self, loop_id: str) -> SimpleNamespace:
+        """Fetch execution-progress snapshot (plan, step_index, iteration, status).
+
+        Returns a namespace with ``plan``, ``step_index``, ``iteration``,
+        ``status`` for the loop's bound checkpoint thread. On RPC failure the
+        fields degrade gracefully (``step_index=0``, ``iteration=0``,
+        ``status=None``, ``plan=None``) so a resume gate can still proceed.
+        """
+        lid = str(loop_id or "").strip()
+        empty = SimpleNamespace(
+            plan=None,
+            step_index=0,
+            iteration=0,
+            status=None,
+            loop_id=lid or None,
+            success=False,
+        )
         if not lid:
-            return
+            return empty
 
         async with self._rpc_lock:
             await self._ensure_rpc_connected()
-            from soothe_sdk.wire.protocol import _serialize_for_json
-
-            payload_values = _serialize_for_json(values)
-            if not isinstance(payload_values, dict):
-                return
-            params: dict[str, Any] = {"loop_id": lid, "values": payload_values}
-            if as_node:
-                params["as_node"] = as_node
-            await self._rpc_client.request(
-                "loop_state_update",
-                params,
-                timeout=timeout,
-            )
+            try:
+                resp = await self._rpc_client.request(
+                    "loop_execution_state_fetch",
+                    {"loop_id": lid},
+                    timeout=30.0,
+                )
+            except Exception:
+                logger.warning(
+                    "loop_execution_state_fetch failed for loop %s", lid[:16], exc_info=True
+                )
+                return empty
+
+        plan = resp.get("plan")
+        step_index_raw = resp.get("step_index")
+        step_index = step_index_raw if isinstance(step_index_raw, int) else 0
+        iteration_raw = resp.get("iteration")
+        iteration = iteration_raw if isinstance(iteration_raw, int) else 0
+        status_raw = resp.get("status")
+        status = status_raw if isinstance(status_raw, str) else None
+        success = bool(resp.get("success", True))
+        return SimpleNamespace(
+            plan=plan,
+            step_index=step_index,
+            iteration=iteration,
+            status=status,
+            loop_id=resp.get("loop_id", lid),
+            success=success,
+        )
 
     async def fetch_conversation_log(
         self,

soothe_client_python-1.0.4/src/soothe_client/appkit/session_store.py → soothe_client_python-1.0.8/src/soothe_client/appkit/loop_session_store.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any, Protocol, runtime_checkable
 
 
-class SessionEntry:
+class LoopSessionEntry:
     """Persisted mapping between an application session id and a daemon loop id."""
 
     __slots__ = (
@@ -63,10 +63,10 @@ class SessionMessage:
 
 
 @runtime_checkable
-class SessionStore(Protocol):
+class LoopSessionStore(Protocol):
     """Persistence seam between appkit and the application's storage backend."""
 
-    async def get_session(self, session_id: str) -> SessionEntry | None:
+    async def get_session(self, session_id: str) -> LoopSessionEntry | None:
         """Return the persisted entry for ``session_id``, or None."""
         ...
 
@@ -97,4 +97,4 @@ class SessionStore(Protocol):
         ...
 
 
-__all__ = ["SessionEntry", "SessionMessage", "SessionStore"]
+__all__ = ["LoopSessionEntry", "SessionMessage", "LoopSessionStore"]

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/appkit/pool.py

@@ -3,7 +3,7 @@
 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``.
+abstracted behind ``LoopSessionStore``.
 """
 
 from __future__ import annotations
@@ -15,6 +15,7 @@ from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from typing import Any
 
+from soothe_client.appkit.loop_session_store import LoopSessionStore
 from soothe_client.appkit.managed_client import (
     BootstrapFunc,
     ClientFactory,
@@ -22,7 +23,6 @@ from soothe_client.appkit.managed_client import (
     default_bootstrap_func,
     default_client_factory,
 )
-from soothe_client.appkit.session_store import SessionStore
 from soothe_client.errors import StaleLoopError
 
 
@@ -96,7 +96,7 @@ class ConnectionPool:
     def __init__(
         self,
         url: str,
-        store: SessionStore,
+        store: LoopSessionStore,
         cfg: PoolConfig | None = None,
         factory: ClientFactory | None = None,
     ) -> None:

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/appkit/turn_runner.py

@@ -21,9 +21,9 @@ from typing import Any
 from soothe_client.appkit.attachments import CompactImageOptions, compact_attachments
 from soothe_client.appkit.broadcaster import SSEBroadcaster, SSEEvent
 from soothe_client.appkit.classifier import ChatEventTerminal, EventClassifier
+from soothe_client.appkit.loop_session_store import LoopSessionStore, SessionMessage
 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
 
@@ -135,7 +135,7 @@ class TurnRunner:
         pool: ConnectionPool,
         gate: QueryGate,
         classifier: EventClassifier,
-        store: SessionStore,
+        store: LoopSessionStore,
         broadcaster: SSEBroadcaster | None,
         cfg: TurnConfig | None = None,
     ) -> None:

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/helpers.py

@@ -428,18 +428,18 @@ async def fetch_loop_history(
     return await client.loop_history_fetch(lid, timeout=timeout)
 
 
-async def fetch_loop_cards(
+async def fetch_execution_state(
     client: WebSocketClient,
     loop_id: str,
     *,
     timeout: float = 30.0,
 ) -> dict[str, Any]:
-    """Fetch the daemon's bound display-card snapshot for a loop."""
+    """Fetch execution-progress snapshot (plan, step_index, iteration, status)."""
     lid = str(loop_id or "").strip()
     if not lid:
         raise ValueError("loop_id is required")
     await _ensure_handshake(client, timeout=timeout)
-    return await client.loop_cards_fetch(lid, timeout=timeout)
+    return await client.loop_execution_state_fetch(lid, timeout=timeout)
 
 
 async def fetch_loop_messages(
@@ -480,6 +480,6 @@ __all__ = [
     "fetch_skills_catalog",
     "fetch_config_section",
     "fetch_loop_history",
-    "fetch_loop_cards",
     "fetch_loop_messages",
+    "fetch_execution_state",
 ]

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/intent_hints.py

@@ -9,8 +9,6 @@ IMAGE_TO_TEXT: Final = "image_to_text"
 OCR: Final = "ocr"
 EMBED: Final = "embed"
 
-REMOVED_INTENT_HINTS: frozenset[str] = frozenset({"direct_llm", "quiz", "direct_model"})
-
 # Default deliverable phases for turn-ending replies (excludes plan_direct narration).
 DEFAULT_DELIVERABLE_PHASES: frozenset[str] = frozenset(
     {

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

@@ -22,7 +22,7 @@ __all__ = [
     "LoopMessagesParams",
     "LoopStateGetParams",
     "LoopStateUpdateParams",
-    "LoopCardsFetchParams",
+    "LoopExecutionStateFetchParams",
     "LoopDetachParams",
     # Subscription params
     "SubscribeParams",
@@ -269,16 +269,17 @@ class LoopStateUpdateParams(ParamsBase):
     as_node: str | None = None
 
 
-class LoopCardsFetchParams(ParamsBase):
-    """Params for ``method=loop_cards_fetch``.
+class LoopExecutionStateFetchParams(ParamsBase):
+    """Params for ``method=loop_execution_state_fetch``.
+
+    Returns a focused execution-progress snapshot (plan, step_index,
+    iteration, status) for the loop's bound checkpoint thread.
 
     Attributes:
         loop_id: Loop identifier (required).
-        since: Fetch cards after this sequence.
     """
 
     loop_id: str = Field(..., min_length=1)
-    since: str | None = None
 
 
 class LoopHistoryFetchParams(ParamsBase):

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/stream_terminal.py

@@ -9,6 +9,11 @@ from __future__ import annotations
 from typing import Any, TypeGuard
 
 from soothe_sdk.core.events import (
+    CARD_CREATED,
+    CARD_FINALIZED,
+    CARD_REPLAY_BEGIN,
+    CARD_REPLAY_END,
+    CARD_UPDATED,
     PLAN_CREATED,
     STRANGE_LOOP_COMPLETED,
     STRANGE_LOOP_STEP_COMPLETED,
@@ -19,6 +24,16 @@ from soothe_sdk.core.events import (
 
 TURN_END_CUSTOM_TYPES = frozenset({STREAM_END, STRANGE_LOOP_COMPLETED})
 
+# ``soothe.stream.end`` reasons that mean the turn was cancelled (not a clean end).
+STREAM_END_CANCEL_REASONS = frozenset(
+    {
+        "cancelled",
+        "canceled",
+        "user_cancelled",
+        "client_disconnect",
+    }
+)
+
 # Customs that prove this turn has real work (not mere intake plan.phase).
 # Intake-only phases must not unlock turn-end — prior-goal stream.end can still
 # arrive after status=running (loop 3e43).
@@ -28,6 +43,9 @@ _TURN_PROGRESS_CUSTOM_TYPES = frozenset(
         STRANGE_LOOP_STEP_STARTED,
         STRANGE_LOOP_STEP_QUEUED,
         STRANGE_LOOP_STEP_COMPLETED,
+        CARD_CREATED,
+        CARD_UPDATED,
+        CARD_FINALIZED,
     }
 )
 
@@ -35,9 +53,9 @@ _TURN_PROGRESS_CUSTOM_TYPES = frozenset(
 STALE_TURN_PENDING_TYPES = frozenset(
     {
         "connection_ack",
-        "card.replay_begin",
-        "card.replay_end",
-        "card.created",
+        CARD_REPLAY_BEGIN,
+        CARD_REPLAY_END,
+        CARD_CREATED,
         "complete",
     }
 )
@@ -56,6 +74,11 @@ def is_turn_end_custom_data(data: Any) -> TypeGuard[dict[str, Any]]:
     return True
 
 
+def is_stream_end_cancel_reason(reason: str | None) -> bool:
+    """True when a ``stream.end`` reason is a cancel/disconnect (not clean end)."""
+    return str(reason or "").strip().lower() in STREAM_END_CANCEL_REASONS
+
+
 def is_turn_progress_chunk(mode: str, data: Any) -> bool:
     """True when a chunk proves the active turn has non-intake progress.
 
@@ -105,8 +128,10 @@ def stale_pending_frame_label(event: dict[str, Any]) -> str | None:
 __all__ = [
     "STALE_TURN_PENDING_TYPES",
     "STREAM_END",
+    "STREAM_END_CANCEL_REASONS",
     "STRANGE_LOOP_COMPLETED",
     "TURN_END_CUSTOM_TYPES",
+    "is_stream_end_cancel_reason",
     "is_turn_end_custom_data",
     "is_turn_progress_chunk",
     "stale_pending_frame_label",

{soothe_client_python-1.0.4 → soothe_client_python-1.0.8}/src/soothe_client/websocket.py

@@ -1066,14 +1066,6 @@ class WebSocketClient:
             timeout=timeout,
         )
 
-    async def loop_cards_fetch(self, loop_id: str, *, timeout: float = 30.0) -> dict[str, Any]:
-        """Fetch bound display-card snapshot (``loop_cards_fetch``)."""
-        return await self.request(
-            "loop_cards_fetch",
-            {"loop_id": loop_id},
-            timeout=timeout,
-        )
-
     async def loop_messages(
         self,
         loop_id: str,
@@ -1103,6 +1095,20 @@ class WebSocketClient:
             timeout=timeout,
         )
 
+    async def loop_execution_state_fetch(
+        self, loop_id: str, *, timeout: float = 30.0
+    ) -> dict[str, Any]:
+        """Fetch execution-progress snapshot (``loop_execution_state_fetch``).
+
+        Returns ``{plan, step_index, iteration, status}`` for the loop's bound
+        checkpoint thread.
+        """
+        return await self.request(
+            "loop_execution_state_fetch",
+            {"loop_id": loop_id},
+            timeout=timeout,
+        )
+
     async def loop_state_update(
         self,
         loop_id: str,