soothe-client-python 0.9.9__tar.gz → 0.9.10__tar.gz

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soothe-client-python
-Version: 0.9.9
+Version: 0.9.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
@@ -69,10 +69,13 @@ More patterns: [`examples/`](examples/) (hello → streaming → multi-turn →
 
 | Need | Use |
 |------|-----|
-| One conversation, stream replies | `DaemonSession` |
+| One conversation, stream replies | `DaemonSession` (`soothe_client.appkit`) |
+| Jobs / cron (async) | `AsyncCommandClient` (alias of `WsCommandClient`) |
+| Jobs / cron (scripts / sync) | `CommandClient` (alias of `SyncWsCommandClient`) |
 | Raw WebSocket / custom RPCs | `WebSocketClient` |
 | Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
-| Jobs / autopilot / cron | `WsCommandClient` |
+
+Wire request param models live in `soothe_client.protocol_params` (not at package root).
 
 ## Develop
 

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/README.md

@@ -36,10 +36,13 @@ More patterns: [`examples/`](examples/) (hello → streaming → multi-turn →
 
 | Need | Use |
 |------|-----|
-| One conversation, stream replies | `DaemonSession` |
+| One conversation, stream replies | `DaemonSession` (`soothe_client.appkit`) |
+| Jobs / cron (async) | `AsyncCommandClient` (alias of `WsCommandClient`) |
+| Jobs / cron (scripts / sync) | `CommandClient` (alias of `SyncWsCommandClient`) |
 | Raw WebSocket / custom RPCs | `WebSocketClient` |
 | Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
-| Jobs / autopilot / cron | `WsCommandClient` |
+
+Wire request param models live in `soothe_client.protocol_params` (not at package root).
 
 ## Develop
 

soothe_client_python-0.9.10/src/soothe_client/__init__.py

@@ -0,0 +1,189 @@
+"""Soothe WebSocket client for talking to a running soothe-daemon.
+
+Public surface (community apps)::
+
+    from soothe_client import WebSocketClient, is_daemon_live
+    from soothe_client.appkit import DaemonSession
+    from soothe_client import AsyncCommandClient, CommandClient  # preferred aliases
+
+Advanced wire validation lives in ``soothe_client.protocol_params``.
+Higher-level session / multi-user helpers live in ``soothe_client.appkit``.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+from typing import Any
+
+from soothe_sdk.wire.codec import ProtocolError
+
+from soothe_client.errors import (
+    DaemonError,
+    DisconnectCause,
+    ReconnectError,
+    StaleLoopError,
+    disconnect_cause_name,
+)
+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,
+)
+from soothe_client.intent_hints import (
+    DEFAULT_DELIVERABLE_PHASES,
+    EMBED,
+    IMAGE_TO_TEXT,
+    OCR,
+    TEXT_COMPLETION,
+    validate_loop_input_intent_hint,
+)
+from soothe_client.session import (
+    bootstrap_loop_session,
+    connect_websocket_with_retries,
+)
+from soothe_client.websocket import WebSocketClient
+from soothe_client.ws_command_client import (
+    AsyncCommandClient,
+    CommandClient,
+    SyncWsCommandClient,
+    WsCommandClient,
+    async_command_client_from_config,
+    async_ws_command_client_from_config,
+    command_client_from_config,
+    ws_command_client_from_config,
+)
+
+try:
+    __version__ = importlib.metadata.version("soothe-client-python")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+# Legacy ``*Params`` names formerly re-exported at package root.
+_LEGACY_PARAM_NAMES = frozenset(
+    {
+        "AuthParams",
+        "AuthRefreshParams",
+        "AutopilotCancelAllParams",
+        "AutopilotCancelGoalParams",
+        "AutopilotDreamParams",
+        "AutopilotGetGoalParams",
+        "AutopilotGetJobParams",
+        "AutopilotListGoalsParams",
+        "AutopilotListJobsParams",
+        "AutopilotResumeParams",
+        "AutopilotStatusParams",
+        "AutopilotSubmitParams",
+        "AutopilotSubscribeParams",
+        "AutopilotWakeParams",
+        "ConfigGetParams",
+        "ConfigReloadParams",
+        "CronAddParams",
+        "CronCancelParams",
+        "CronListParams",
+        "CronShowParams",
+        "DaemonShutdownParams",
+        "DaemonStatusParams",
+        "DisconnectParams",
+        "InvokeSkillParams",
+        "JobCancelParams",
+        "JobCreateParams",
+        "JobDagParams",
+        "JobGuidanceParams",
+        "JobPauseParams",
+        "JobResumeParams",
+        "JobStatusParams",
+        "LoopCardsFetchParams",
+        "LoopDeleteParams",
+        "LoopDetachParams",
+        "LoopGetParams",
+        "LoopInputParams",
+        "LoopListParams",
+        "LoopMessagesParams",
+        "LoopNewParams",
+        "LoopPruneParams",
+        "LoopReattachParams",
+        "LoopStateGetParams",
+        "LoopStateUpdateParams",
+        "LoopTreeParams",
+        "McpStatusParams",
+        "ModelsListParams",
+        "RpcCommandParams",
+        "SkillsListParams",
+        "SlashCommandParams",
+        "SubscribeParams",
+    }
+)
+
+__all__ = [
+    "__version__",
+    # Transport
+    "WebSocketClient",
+    "ProtocolError",
+    # Errors
+    "DaemonError",
+    "DisconnectCause",
+    "ReconnectError",
+    "StaleLoopError",
+    "disconnect_cause_name",
+    # Command clients (canonical + preferred aliases)
+    "WsCommandClient",
+    "SyncWsCommandClient",
+    "AsyncCommandClient",
+    "CommandClient",
+    "ws_command_client_from_config",
+    "async_ws_command_client_from_config",
+    "command_client_from_config",
+    "async_command_client_from_config",
+    # Session bootstrap
+    "bootstrap_loop_session",
+    "connect_websocket_with_retries",
+    # Helpers
+    "websocket_url_from_config",
+    "connected_websocket",
+    "protocol1_rpc",
+    "check_daemon_status",
+    "is_daemon_live",
+    "request_daemon_config_reload",
+    "request_daemon_shutdown",
+    "fetch_skills_catalog",
+    "fetch_config_section",
+    "fetch_loop_history",
+    "fetch_loop_cards",
+    "fetch_loop_messages",
+    # Intent hints
+    "TEXT_COMPLETION",
+    "IMAGE_TO_TEXT",
+    "OCR",
+    "EMBED",
+    "DEFAULT_DELIVERABLE_PHASES",
+    "validate_loop_input_intent_hint",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load legacy ``*Params`` with a deprecation warning.
+
+    Prefer ``from soothe_client.protocol_params import LoopInputParams``.
+    """
+    if name in _LEGACY_PARAM_NAMES:
+        warnings.warn(
+            f"Importing {name!r} from soothe_client is deprecated; "
+            f"use soothe_client.protocol_params.{name} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from soothe_client import protocol_params as _params
+
+        return getattr(_params, name)
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/appkit/__init__.py

@@ -1,13 +1,16 @@
 """Application helpers built on WebSocketClient.
 
-Product-agnostic building blocks for agent UIs and backends:
+Primary building blocks for agent UIs and backends:
 
 - ``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
+- ``EventClassifier`` — stream → deliverable mapping
 - ``SSEBroadcaster`` — drop-on-full fan-out to subscribers
 - ``SessionStore`` — persistence seam (Protocol)
+
+Advanced stream/pipeline plumbing lives in submodules
+(``events``, ``chunk_filter``, ``turn``, ``managed_client``).
 """
 
 from __future__ import annotations
@@ -18,7 +21,6 @@ from soothe_client.appkit.attachments import (
     compact_image_attachment,
 )
 from soothe_client.appkit.broadcaster import SSEBroadcaster, SSEEvent
-from soothe_client.appkit.chunk_filter import should_drop_stream_chunk_early
 from soothe_client.appkit.classifier import (
     EVENT_FINAL_REPORT,
     ChatEventResult,
@@ -26,17 +28,7 @@ from soothe_client.appkit.classifier import (
     ClassifierConfig,
     EventClassifier,
 )
-from soothe_client.appkit.daemon_session import DEFAULT_POST_IDLE_DRAIN_S, DaemonSession
-from soothe_client.appkit.events import is_loop_scoped_event, unwrap_next
-from soothe_client.appkit.managed_client import (
-    BootstrapFunc,
-    ClientFactory,
-    ManagedClient,
-    WebSocketManagedClient,
-    default_bootstrap_func,
-    default_client_factory,
-)
-from soothe_client.appkit.observability import TurnEventStats
+from soothe_client.appkit.daemon_session import DaemonSession
 from soothe_client.appkit.pool import (
     ConnectionPool,
     ErrPoolExhausted,
@@ -50,15 +42,6 @@ from soothe_client.appkit.thinking_step import (
     DEFAULT_THINKING_STEP_EVENTS,
     extract_thinking_step,
 )
-from soothe_client.appkit.turn import (
-    PRIORITY_CRITICAL,
-    PRIORITY_HIGH,
-    PRIORITY_LOW,
-    PRIORITY_NORMAL,
-    TurnApplyBatcher,
-    TurnEventPipeline,
-    run_turn_pipeline,
-)
 from soothe_client.appkit.turn_runner import (
     STREAM_CLOSE_FAIL,
     STREAM_CLOSE_SOFT_COMPLETE,
@@ -77,13 +60,13 @@ from soothe_client.appkit.turn_runner import (
 )
 
 __all__ = [
-    "DEFAULT_POST_IDLE_DRAIN_S",
     "DEFAULT_THINKING_STEP_EVENTS",
     "STREAM_CLOSE_FAIL",
     "STREAM_CLOSE_SOFT_COMPLETE",
     "Attachment",
-    "BootstrapFunc",
-    "ClientFactory",
+    "ChatEventResult",
+    "ChatEventTerminal",
+    "ClassifierConfig",
     "CompactImageOptions",
     "ConnectionPool",
     "DaemonSession",
@@ -92,18 +75,10 @@ __all__ = [
     "ErrPoolExhausted",
     "ErrQueryBusy",
     "ErrQueryTimeout",
-    "ChatEventResult",
-    "ChatEventTerminal",
-    "ClassifierConfig",
     "EventClassifier",
     "InputOpts",
-    "ManagedClient",
     "OnComplete",
     "OnError",
-    "PRIORITY_CRITICAL",
-    "PRIORITY_HIGH",
-    "PRIORITY_LOW",
-    "PRIORITY_NORMAL",
     "PoolConfig",
     "PooledConn",
     "QueryGate",
@@ -114,22 +89,12 @@ __all__ = [
     "SessionStore",
     "StreamClosePolicy",
     "TimeoutPolicy",
-    "TurnApplyBatcher",
     "TurnConfig",
-    "TurnEventPipeline",
-    "TurnEventStats",
     "TurnRunner",
-    "WebSocketManagedClient",
     "compact_attachments",
     "compact_image_attachment",
-    "default_bootstrap_func",
-    "default_client_factory",
     "default_pool_config",
     "extract_thinking_step",
     "idle_timeout_for_turn",
     "input_message_for_loop",
-    "is_loop_scoped_event",
-    "run_turn_pipeline",
-    "should_drop_stream_chunk_early",
-    "unwrap_next",
 ]

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/appkit/daemon_session.py

@@ -37,7 +37,21 @@ StreamDeliveryResolver = Callable[[], str]
 
 
 class DaemonSession:
-    """Daemon-backed loop session with stream + RPC sockets."""
+    """One conversation with a daemon loop: connect, send turns, stream chunks.
+
+    Owns a subscribed stream WebSocket plus an RPC sidecar so metadata calls
+    do not starve loop events. Typical usage::
+
+        session = DaemonSession("ws://127.0.0.1:8765")
+        await session.connect()
+        await session.send_turn("Hello")
+        async for _ns, mode, data in session.iter_turn_chunks():
+            ...
+        await session.close()
+
+    Advanced: ``early_drop_fn`` / ``stats_factory`` customize stream filtering
+    and metrics for product UIs; most apps leave the defaults.
+    """
 
     def __init__(
         self,
@@ -67,7 +81,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
-        # IG-659: last completed turn's seq floor (drop stale prior-turn frames).
+        # Last completed turn's seq floor (drop stale prior-turn frames).
         self._last_turn_end_seq: int = 0
         self._expected_turn_id: str | None = None
 
@@ -108,7 +122,11 @@ class DaemonSession:
         )
 
     async def connect(self, *, resume_loop_id: str | None = None) -> dict[str, Any]:
-        """Connect and bootstrap a daemon loop session."""
+        """Open the stream socket and bootstrap (or resume) a loop session.
+
+        Returns:
+            Status event from the daemon (includes ``loop_id`` on success).
+        """
         await connect_websocket_with_retries(self._client)
         return await self._bootstrap_loop(resume_loop_id=resume_loop_id)
 
@@ -182,7 +200,7 @@ class DaemonSession:
         await self._bootstrap_loop(resume_loop_id=resume_loop_id)
 
     async def close(self, *, handshake_timeout: float = 2.0) -> None:
-        """Close stream and RPC sockets (idempotent)."""
+        """Close stream and RPC sockets. Safe to call more than once."""
         if self._closed:
             return
         self._closed = True
@@ -219,7 +237,11 @@ class DaemonSession:
         clarification_answers: list[str] | None = None,
         intent_hint: str | None = None,
     ) -> None:
-        """Send a new user turn to the daemon."""
+        """Send a user message on the active loop (start of a turn).
+
+        Call ``iter_turn_chunks`` afterward to consume the streamed reply.
+        Requires ``connect()`` (or another bootstrap) first.
+        """
         if not self._loop_id:
             raise RuntimeError("No active loop session")
         await self._client.send_input(
@@ -303,13 +325,15 @@ class DaemonSession:
         *,
         max_wait_s: float | None = None,
     ) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
-        """Yield ``(namespace, mode, data)`` chunks for the active daemon turn.
+        """Yield ``(namespace, mode, data)`` stream chunks until the turn ends.
+
+        Handles idle timeout, post-idle drain, and turn boundary filtering.
+        Call after ``send_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).
+                signal in time.
         """
         self.turn_event_stats = self._new_turn_stats()
         self.last_turn_end_state = None

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/helpers.py

@@ -1,4 +1,8 @@
-"""WebSocket helper functions for daemon communication."""
+"""Small WebSocket helpers for CLI and scripts (status, fetch, one-shot RPC).
+
+For interactive turns use ``DaemonSession``. For jobs/cron use
+``WsCommandClient`` / ``CommandClient``.
+"""
 
 from __future__ import annotations
 

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/protocol_params.py

@@ -32,6 +32,7 @@ __all__ = [
     "AutopilotListGoalsParams",
     "AutopilotGetGoalParams",
     "AutopilotCancelGoalParams",
+    "AutopilotCancelAllParams",
     "AutopilotWakeParams",
     "AutopilotDreamParams",
     "AutopilotResumeParams",
@@ -363,6 +364,10 @@ class AutopilotCancelGoalParams(ParamsBase):
     goal_id: str = Field(..., min_length=1)
 
 
+class AutopilotCancelAllParams(EmptyParams):
+    """Params for ``method=autopilot_cancel_all`` — no required fields."""
+
+
 class AutopilotWakeParams(EmptyParams):
     """Params for ``method=autopilot_wake`` — no required fields."""
 

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/session.py

@@ -1,4 +1,8 @@
-"""Shared WebSocket session bootstrap for CLI headless and TUI."""
+"""Session bootstrap helpers for CLI, TUI, and appkit.
+
+Prefer ``DaemonSession`` for application code. These helpers are the lower-level
+connect + loop-subscribe steps used when you own the ``WebSocketClient``.
+"""
 
 from __future__ import annotations
 
@@ -22,14 +26,7 @@ _LEGACY_LOOP_AUTOPILOT_MODE = "solo"
 
 
 async def connect_websocket_with_retries(client: Any) -> None:
-    """Connect to the daemon with bounded retries for cold-start races.
-
-    Args:
-        client: WebSocketClient instance.
-
-    Raises:
-        ConnectionError: If connection fails after all retries.
-    """
+    """Connect a ``WebSocketClient`` with retries (daemon cold-start safe)."""
     last_error: OSError | ConnectionError | TimeoutError | None = None
     for attempt in range(_CONNECT_RETRY_COUNT):
         try:

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/stream_terminal.py

@@ -1,7 +1,7 @@
-"""Shared stream/turn terminal frame helpers for WebSocket and DaemonSession.
+"""Internal stream/turn terminal frame helpers.
 
-Keeps peel-at-turn-start and turn-end detection on one vocabulary so leftover
-prior-goal terminals cannot blank the next TUI query.
+Used by ``WebSocketClient`` and ``DaemonSession`` so leftover prior-turn
+terminals cannot blank the next query. Not part of the community public API.
 """
 
 from __future__ import annotations

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/turn_boundary.py

@@ -1,7 +1,8 @@
-"""Turn / stream boundary helpers (IG-659).
+"""Internal turn / stream boundary helpers.
 
-``turn_id`` correlates a user turn across status, events, and terminals.
-``seq`` is a daemon-assigned monotonic counter per loop for drop-stale filtering.
+Used by ``DaemonSession`` and ``WebSocketClient`` for ``turn_id`` / ``seq``
+filtering. Not part of the community public API — import only if you are
+extending stream handling.
 """
 
 from __future__ import annotations

{soothe_client_python-0.9.9 → soothe_client_python-0.9.10}/src/soothe_client/ws_command_client.py

@@ -141,6 +141,7 @@ _AUTOPilot_COMMANDS = {
     "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",
@@ -162,19 +163,27 @@ _MEMORY_COMMANDS = {
 
 
 class WsCommandClient:
-    """Async WebSocket client for daemon command endpoints.
+    """Async client for one-shot daemon RPCs (jobs, autopilot, cron).
 
-    Connects to daemon WebSocket, sends command messages, and waits for
-    response messages with a request/response pattern.
+    Prefer this for asyncio apps. For scripts/CLI without an event loop, use
+    ``SyncWsCommandClient`` (alias ``CommandClient``). For streaming agent
+    turns, use ``DaemonSession`` instead.
 
-    Usage:
-        client = WsCommandClient(ws_url)
-        result = await client.autopilot_status()
-        result = await client.cron_add("in 1 hour remind me to deploy")
+    Preferred community alias: ``AsyncCommandClient``.
+
+    Job lifecycle uses ``job_*`` methods. Autopilot goal helpers use
+    ``autopilot_*``. ``job_cancel`` cancels a root job and its descendants;
+    ``autopilot_cancel_all`` cancels every open goal in one call.
+
+    Example::
+
+        client = WsCommandClient("ws://127.0.0.1:8765")
+        created = await client.job_create("Summarize the README")
+        await client.job_cancel(created["job_id"])
 
     Args:
-        ws_url: WebSocket URL (e.g. ``ws://127.0.0.1:8765``).
-        timeout: Command timeout in seconds.
+        ws_url: Daemon WebSocket URL (e.g. ``ws://127.0.0.1:8765``).
+        timeout: Per-command timeout in seconds.
     """
 
     def __init__(self, ws_url: str, *, timeout: float = 30.0) -> None:
@@ -259,35 +268,43 @@ class WsCommandClient:
         except Exception as exc:
             raise RuntimeError(f"Command failed: {exc}") from exc
 
-    # Autopilot commands
+    # --- Autopilot goals -------------------------------------------------
 
     async def autopilot_status(self) -> dict[str, Any]:
-        """Get autopilot status."""
+        """Return autopilot scheduler status (running / dreaming / pool)."""
         return await self._send_command("autopilot_status")
 
     async def autopilot_submit(
         self, description: str, *, priority: int = 50, workspace: str | None = None
     ) -> dict[str, Any]:
-        """Submit a new autopilot task."""
+        """Submit a new autopilot goal (returns ``goal_id``)."""
         payload: dict[str, Any] = {"description": description, "priority": priority}
         if workspace:
             payload["workspace"] = workspace
         return await self._send_command("autopilot_submit", payload)
 
     async def autopilot_list_goals(self) -> dict[str, Any]:
-        """List all goals."""
+        """List all goals (including non-root children)."""
         return await self._send_command("autopilot_list_goals")
 
     async def autopilot_get_goal(self, goal_id: str) -> dict[str, Any]:
-        """Get goal details."""
+        """Fetch one goal by id."""
         return await self._send_command("autopilot_get_goal", {"goal_id": goal_id})
 
     async def autopilot_cancel_goal(self, goal_id: str) -> dict[str, Any]:
-        """Cancel a goal."""
+        """Cancel a goal and its non-terminal descendants."""
         return await self._send_command("autopilot_cancel_goal", {"goal_id": goal_id})
 
+    async def autopilot_cancel_all(self) -> dict[str, Any]:
+        """Cancel every open (non-terminal) goal in one call.
+
+        Prefer ``job_cancel(job_id)`` when you know the job root. Use this when
+        you need a bulk stop of leftover pending/active goals.
+        """
+        return await self._send_command("autopilot_cancel_all")
+
     async def autopilot_wake(self) -> dict[str, Any]:
-        """Exit dreaming mode."""
+        """Exit dreaming mode and resume scheduling."""
         return await self._send_command("autopilot_wake")
 
     async def autopilot_dream(self) -> dict[str, Any]:
@@ -295,26 +312,26 @@ class WsCommandClient:
         return await self._send_command("autopilot_dream")
 
     async def autopilot_resume(self, goal_id: str) -> dict[str, Any]:
-        """Resume a suspended/blocked goal."""
+        """Resume a suspended or blocked goal."""
         return await self._send_command("autopilot_resume", {"goal_id": goal_id})
 
     async def autopilot_list_jobs(self) -> dict[str, Any]:
-        """List root goals (jobs) only."""
+        """List root goals only (jobs). Prefer ``job_*`` for job control."""
         return await self._send_command("autopilot_list_jobs")
 
     async def autopilot_get_job(self, job_id: str) -> dict[str, Any]:
-        """Get job status with DAG snapshot."""
+        """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_subscribe(self) -> dict[str, Any]:
-        """Subscribe to autopilot worker events."""
+        """Subscribe this connection to autopilot worker events."""
         return await self._send_command("autopilot_subscribe")
 
     async def autopilot_unsubscribe(self) -> dict[str, Any]:
         """Unsubscribe from autopilot worker events."""
         return await self._send_command("autopilot_unsubscribe")
 
-    # canonical job commands (recommended)
+    # --- Jobs (preferred for job lifecycle) ------------------------------
 
     async def job_create(
         self,
@@ -325,18 +342,7 @@ class WsCommandClient:
         max_iterations: int | None = None,
         guidance: str | None = None,
     ) -> dict[str, Any]:
-        """Create a new autopilot job.
-
-        Args:
-            goal: Job goal text (required).
-            workspace: Optional workspace path.
-            autonomous: Whether to run autonomously.
-            max_iterations: Optional iteration limit.
-            guidance: Optional initial guidance.
-
-        Returns:
-            Dict with job_id and status.
-        """
+        """Create a background job (root goal). Returns ``job_id`` + status."""
         payload: dict[str, Any] = {"goal": goal}
         if workspace:
             payload["workspace"] = workspace
@@ -349,79 +355,35 @@ class WsCommandClient:
         return await self._send_command("job_create", payload)
 
     async def job_status(self, job_id: str) -> dict[str, Any]:
-        """Get job status with goal counts and workers.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            Dict with job_id, status, active_goals, completed_goals, workers.
-        """
+        """Get job status with goal counts and workers."""
         return await self._send_command("job_status", {"job_id": job_id})
 
     async def job_pause(self, job_id: str) -> dict[str, Any]:
-        """Pause a running job.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            Dict with job_id and status="suspended".
-        """
+        """Pause a running job (status becomes suspended)."""
         return await self._send_command("job_pause", {"job_id": job_id})
 
     async def job_resume(self, job_id: str) -> dict[str, Any]:
-        """Resume a paused job.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            Dict with job_id and status="pending".
-        """
+        """Resume a paused job."""
         return await self._send_command("job_resume", {"job_id": job_id})
 
     async def job_cancel(self, job_id: str) -> dict[str, Any]:
-        """Cancel a job.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            Dict with job_id and status="cancelled".
-        """
+        """Cancel a job root and all non-terminal descendants."""
         return await self._send_command("job_cancel", {"job_id": job_id})
 
     async def job_dag(self, job_id: str) -> dict[str, Any]:
-        """Get job DAG snapshot for visualization.
-
-        Args:
-            job_id: Job identifier.
-
-        Returns:
-            Dict with job_id and dag (nodes/edges).
-        """
+        """Get the job goal DAG (nodes/edges) for visualization."""
         return await self._send_command("job_dag", {"job_id": job_id})
 
     async def job_guidance(
         self, job_id: str, content: str, *, goal_id: str | None = None
     ) -> dict[str, Any]:
-        """Send guidance to a job or specific goal.
-
-        Args:
-            job_id: Job identifier.
-            content: Guidance text.
-            goal_id: Optional specific goal to target.
-
-        Returns:
-            Dict with job_id, goal_id, absorbed.
-        """
+        """Send guidance text to a job or a specific goal under it."""
         payload: dict[str, Any] = {"job_id": job_id, "content": content}
         if goal_id:
             payload["goal_id"] = goal_id
         return await self._send_command("job_guidance", payload)
 
-    # Cron commands
+    # --- Cron ------------------------------------------------------------
 
     async def cron_add(self, text: str, *, priority: int | None = None) -> dict[str, Any]:
         """Submit a natural-language scheduled job."""
@@ -432,75 +394,63 @@ class WsCommandClient:
         return _normalize_cron_add_result(result)
 
     async def cron_list(self, *, status: str | None = None) -> dict[str, Any]:
-        """List scheduled jobs.
-
-        Sends the ``cron_list`` method, which the daemon routes to
-        ``_handle_cron_list``. The former ``cron_list_jobs`` method name is
-        deprecated; it sent a method the daemon did not handle.
-
-        Args:
-            status: Optional status filter.
-
-        Returns:
-            Dict with jobs list.
-        """
+        """List scheduled cron jobs (optional ``status`` filter)."""
         payload: dict[str, Any] = {}
         if status:
             payload["status"] = status
         return await self._send_command("cron_list", payload)
 
     async def cron_show(self, job_id: str) -> dict[str, Any]:
-        """Get job details."""
+        """Get details for one cron job."""
         result = await self._send_command("cron_show", {"job_id": job_id})
         return _normalize_cron_show_result(result)
 
     async def cron_cancel(self, job_id: str) -> dict[str, Any]:
-        """Cancel a scheduled job."""
+        """Cancel a scheduled cron job."""
         return await self._send_command("cron_cancel", {"job_id": job_id})
 
-    # Memory commands
+    # --- Memory (admin) --------------------------------------------------
 
     async def memory_stats(self, mode: str = "daemon") -> dict[str, Any]:
-        """Query daemon memory profiling stats."""
+        """Query daemon memory profiling stats (admin)."""
         return await self._send_command("memory_stats", {"mode": mode})
 
 
 class SyncWsCommandClient:
-    """Synchronous wrapper for WsCommandClient.
+    """Synchronous wrapper around ``WsCommandClient`` for scripts and CLI.
 
-    Provides a synchronous interface for CLI commands that need to call
-    daemon endpoints without async context.
+    Preferred community alias: ``CommandClient``. Each method opens a short
+    WebSocket RPC (same behavior as the async client).
 
     Args:
-        ws_url: WebSocket URL.
-        timeout: Command timeout in seconds.
+        ws_url: Daemon WebSocket URL.
+        timeout: Per-command timeout in seconds.
     """
 
     def __init__(self, ws_url: str, *, timeout: float = 30.0) -> None:
         self._client = WsCommandClient(ws_url, timeout=timeout)
 
     def _run_async(self, coro: Any) -> Any:
-        """Run async coroutine in sync context."""
+        """Run an async coroutine from sync code."""
         try:
             loop = asyncio.get_running_loop()
         except RuntimeError:
             loop = None
 
         if loop is not None:
-            # Already in async context - create task
             return asyncio.ensure_future(coro)
-        else:
-            # Not in async context - run in new loop
-            return asyncio.run(coro)
+        return asyncio.run(coro)
+
+    # --- Autopilot goals -------------------------------------------------
 
     def autopilot_status(self) -> dict[str, Any]:
-        """Get autopilot status (sync)."""
+        """Return autopilot scheduler status."""
         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
     ) -> dict[str, Any]:
-        """Submit a new autopilot task (sync)."""
+        """Submit a new autopilot goal."""
         return cast(
             dict[str, Any],
             self._run_async(
@@ -509,47 +459,50 @@ class SyncWsCommandClient:
         )
 
     def autopilot_list_goals(self) -> dict[str, Any]:
-        """List all goals (sync)."""
+        """List all goals."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_list_goals()))
 
     def autopilot_get_goal(self, goal_id: str) -> dict[str, Any]:
-        """Get goal details (sync)."""
+        """Fetch one goal by id."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_get_goal(goal_id)))
 
     def autopilot_cancel_goal(self, goal_id: str) -> dict[str, Any]:
-        """Cancel a goal (sync)."""
+        """Cancel a goal and its non-terminal descendants."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_cancel_goal(goal_id)))
 
+    def autopilot_cancel_all(self) -> dict[str, Any]:
+        """Cancel every open (non-terminal) goal."""
+        return cast(dict[str, Any], self._run_async(self._client.autopilot_cancel_all()))
+
     def autopilot_wake(self) -> dict[str, Any]:
-        """Exit dreaming mode (sync)."""
+        """Exit dreaming mode."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_wake()))
 
     def autopilot_dream(self) -> dict[str, Any]:
-        """Force dreaming mode (sync)."""
+        """Force dreaming mode."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_dream()))
 
     def autopilot_resume(self, goal_id: str) -> dict[str, Any]:
-        """Resume a suspended/blocked goal (sync)."""
+        """Resume a suspended or blocked goal."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_resume(goal_id)))
 
     def autopilot_list_jobs(self) -> dict[str, Any]:
-        """List root goals (jobs) only (sync)."""
+        """List root goals only (jobs)."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_list_jobs()))
 
     def autopilot_get_job(self, job_id: str) -> dict[str, Any]:
-        """Get job status with DAG snapshot (sync)."""
+        """Get a root job with DAG snapshot."""
         return cast(dict[str, Any], self._run_async(self._client.autopilot_get_job(job_id)))
 
-    def job_pause(self, job_id: str) -> dict[str, Any]:
-        """Pause a running autopilot job (sync)."""
-        return cast(dict[str, Any], self._run_async(self._client.job_pause(job_id)))
+    def autopilot_subscribe(self) -> dict[str, Any]:
+        """Subscribe to autopilot worker events."""
+        return cast(dict[str, Any], self._run_async(self._client.autopilot_subscribe()))
 
-    def job_guidance(self, job_id: str, text: str, *, goal_id: str | None = None) -> dict[str, Any]:
-        """Send guidance to an autopilot job or specific goal (sync)."""
-        return cast(
-            dict[str, Any],
-            self._run_async(self._client.job_guidance(job_id, text, goal_id=goal_id)),
-        )
+    def autopilot_unsubscribe(self) -> dict[str, Any]:
+        """Unsubscribe from autopilot worker events."""
+        return cast(dict[str, Any], self._run_async(self._client.autopilot_unsubscribe()))
+
+    # --- Jobs ------------------------------------------------------------
 
     def job_create(
         self,
@@ -560,7 +513,7 @@ class SyncWsCommandClient:
         max_iterations: int | None = None,
         guidance: str | None = None,
     ) -> dict[str, Any]:
-        """Create a new autopilot job."""
+        """Create a background job (root goal)."""
         return cast(
             dict[str, Any],
             self._run_async(
@@ -578,68 +531,69 @@ class SyncWsCommandClient:
         """Get job status with goal counts and workers."""
         return cast(dict[str, Any], self._run_async(self._client.job_status(job_id)))
 
+    def job_pause(self, job_id: str) -> dict[str, Any]:
+        """Pause a running job."""
+        return cast(dict[str, Any], self._run_async(self._client.job_pause(job_id)))
+
     def job_resume(self, job_id: str) -> dict[str, Any]:
-        """Resume a paused autopilot job."""
+        """Resume a paused job."""
         return cast(dict[str, Any], self._run_async(self._client.job_resume(job_id)))
 
     def job_cancel(self, job_id: str) -> dict[str, Any]:
-        """Cancel an autopilot job."""
+        """Cancel a job root and all non-terminal descendants."""
         return cast(dict[str, Any], self._run_async(self._client.job_cancel(job_id)))
 
     def job_dag(self, job_id: str) -> dict[str, Any]:
-        """Get job DAG snapshot for visualization."""
+        """Get the job goal DAG for visualization."""
         return cast(dict[str, Any], self._run_async(self._client.job_dag(job_id)))
 
-    def autopilot_subscribe(self) -> dict[str, Any]:
-        """Subscribe to autopilot worker events (sync)."""
-        return cast(dict[str, Any], self._run_async(self._client.autopilot_subscribe()))
+    def job_guidance(
+        self, job_id: str, content: str, *, goal_id: str | None = None
+    ) -> dict[str, Any]:
+        """Send guidance text to a job or a specific goal under it."""
+        return cast(
+            dict[str, Any],
+            self._run_async(self._client.job_guidance(job_id, content, goal_id=goal_id)),
+        )
 
-    def autopilot_unsubscribe(self) -> dict[str, Any]:
-        """Unsubscribe from autopilot worker events (sync)."""
-        return cast(dict[str, Any], self._run_async(self._client.autopilot_unsubscribe()))
+    # --- Cron ------------------------------------------------------------
 
     def cron_add(self, text: str, *, priority: int | None = None) -> dict[str, Any]:
-        """Submit a natural-language scheduled job (sync)."""
+        """Submit a natural-language scheduled job."""
         return cast(dict[str, Any], self._run_async(self._client.cron_add(text, priority=priority)))
 
     def cron_list(self, *, status: str | None = None) -> dict[str, Any]:
-        """List scheduled jobs (sync)."""
+        """List scheduled cron jobs."""
         return cast(dict[str, Any], self._run_async(self._client.cron_list(status=status)))
 
     def cron_show(self, job_id: str) -> dict[str, Any]:
-        """Get job details (sync)."""
+        """Get details for one cron job."""
         return cast(dict[str, Any], self._run_async(self._client.cron_show(job_id)))
 
     def cron_cancel(self, job_id: str) -> dict[str, Any]:
-        """Cancel a scheduled job (sync)."""
+        """Cancel a scheduled cron job."""
         return cast(dict[str, Any], self._run_async(self._client.cron_cancel(job_id)))
 
+    # --- Memory (admin) --------------------------------------------------
+
     def memory_stats(self, mode: str = "daemon") -> dict[str, Any]:
-        """Query daemon memory profiling stats (sync)."""
+        """Query daemon memory profiling stats (admin)."""
         return cast(dict[str, Any], self._run_async(self._client.memory_stats(mode)))
 
 
 def ws_command_client_from_config(cfg: Any) -> SyncWsCommandClient:
-    """Build a WebSocket command client from CLI or soothe config.
+    """Build a sync command client from soothe/CLI config (host/port).
 
-    Args:
-        cfg: CLI, daemon, or soothe config exposing websocket host/port.
-
-    Returns:
-        SyncWsCommandClient instance.
+    Preferred alias: ``command_client_from_config``.
     """
     ws_url = websocket_url_from_config(cfg)
     return SyncWsCommandClient(ws_url)
 
 
 def async_ws_command_client_from_config(cfg: Any) -> WsCommandClient:
-    """Build an async WebSocket command client from config.
-
-    Args:
-        cfg: CLI, daemon, or soothe config exposing websocket host/port.
+    """Build an async command client from soothe/CLI config (host/port).
 
-    Returns:
-        WsCommandClient instance.
+    Preferred alias: ``async_command_client_from_config``.
     """
     ws_url = websocket_url_from_config(cfg)
     return WsCommandClient(ws_url)
@@ -648,6 +602,17 @@ def async_ws_command_client_from_config(cfg: Any) -> WsCommandClient:
 __all__ = [
     "WsCommandClient",
     "SyncWsCommandClient",
+    "AsyncCommandClient",
+    "CommandClient",
     "ws_command_client_from_config",
     "async_ws_command_client_from_config",
+    "command_client_from_config",
+    "async_command_client_from_config",
 ]
+
+
+# Preferred community names (aliases; wire method names unchanged).
+AsyncCommandClient = WsCommandClient
+CommandClient = SyncWsCommandClient
+command_client_from_config = ws_command_client_from_config
+async_command_client_from_config = async_ws_command_client_from_config

soothe_client_python-0.9.9/src/soothe_client/__init__.py

@@ -1,194 +0,0 @@
-"""Soothe WebSocket client for talking to a running soothe-daemon.
-
-Transport helpers (connect, loops, RPCs) live here. Higher-level session
-and multi-user turn tools live in ``soothe_client.appkit``.
-"""
-
-from __future__ import annotations
-
-import importlib.metadata
-
-from soothe_sdk.core.types import VerbosityLevel
-from soothe_sdk.wire.codec import ProtocolError
-
-from soothe_client.errors import (
-    DaemonError,
-    DisconnectCause,
-    ReconnectError,
-    StaleLoopError,
-    disconnect_cause_name,
-)
-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,
-)
-from soothe_client.intent_hints import (
-    DEFAULT_DELIVERABLE_PHASES,
-    EMBED,
-    IMAGE_TO_TEXT,
-    OCR,
-    TEXT_COMPLETION,
-    validate_loop_input_intent_hint,
-)
-from soothe_client.protocol_params import (
-    AuthParams,
-    AuthRefreshParams,
-    AutopilotCancelGoalParams,
-    AutopilotDreamParams,
-    AutopilotGetGoalParams,
-    AutopilotGetJobParams,
-    AutopilotListGoalsParams,
-    AutopilotListJobsParams,
-    AutopilotResumeParams,
-    AutopilotStatusParams,
-    AutopilotSubmitParams,
-    AutopilotSubscribeParams,
-    AutopilotWakeParams,
-    ConfigGetParams,
-    ConfigReloadParams,
-    CronAddParams,
-    CronCancelParams,
-    CronListParams,
-    CronShowParams,
-    DaemonShutdownParams,
-    DaemonStatusParams,
-    DisconnectParams,
-    InvokeSkillParams,
-    JobCancelParams,
-    JobCreateParams,
-    JobDagParams,
-    JobGuidanceParams,
-    JobPauseParams,
-    JobResumeParams,
-    JobStatusParams,
-    LoopCardsFetchParams,
-    LoopDeleteParams,
-    LoopDetachParams,
-    LoopGetParams,
-    LoopInputParams,
-    LoopListParams,
-    LoopMessagesParams,
-    LoopNewParams,
-    LoopPruneParams,
-    LoopReattachParams,
-    LoopStateGetParams,
-    LoopStateUpdateParams,
-    LoopTreeParams,
-    McpStatusParams,
-    ModelsListParams,
-    RpcCommandParams,
-    SkillsListParams,
-    SlashCommandParams,
-    SubscribeParams,
-)
-from soothe_client.session import (
-    bootstrap_loop_session,
-    connect_websocket_with_retries,
-)
-from soothe_client.websocket import WebSocketClient
-from soothe_client.ws_command_client import (
-    SyncWsCommandClient,
-    WsCommandClient,
-    async_ws_command_client_from_config,
-    ws_command_client_from_config,
-)
-
-try:
-    __version__ = importlib.metadata.version("soothe-client-python")
-except importlib.metadata.PackageNotFoundError:
-    __version__ = "0.0.0"
-
-__all__ = [
-    "__version__",
-    "WebSocketClient",
-    "VerbosityLevel",
-    "ProtocolError",
-    "DaemonError",
-    "DisconnectCause",
-    "ReconnectError",
-    "StaleLoopError",
-    "disconnect_cause_name",
-    "WsCommandClient",
-    "SyncWsCommandClient",
-    "ws_command_client_from_config",
-    "async_ws_command_client_from_config",
-    "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",
-    "request_daemon_shutdown",
-    "fetch_skills_catalog",
-    "fetch_config_section",
-    "fetch_loop_history",
-    "fetch_loop_cards",
-    "fetch_loop_messages",
-    "TEXT_COMPLETION",
-    "IMAGE_TO_TEXT",
-    "OCR",
-    "EMBED",
-    "DEFAULT_DELIVERABLE_PHASES",
-    "validate_loop_input_intent_hint",
-    "LoopGetParams",
-    "LoopListParams",
-    "LoopTreeParams",
-    "LoopPruneParams",
-    "LoopDeleteParams",
-    "LoopNewParams",
-    "LoopReattachParams",
-    "LoopInputParams",
-    "LoopMessagesParams",
-    "LoopStateGetParams",
-    "LoopStateUpdateParams",
-    "LoopCardsFetchParams",
-    "LoopDetachParams",
-    "SubscribeParams",
-    "AutopilotSubscribeParams",
-    "AutopilotStatusParams",
-    "AutopilotSubmitParams",
-    "AutopilotListGoalsParams",
-    "AutopilotGetGoalParams",
-    "AutopilotCancelGoalParams",
-    "AutopilotWakeParams",
-    "AutopilotDreamParams",
-    "AutopilotResumeParams",
-    "AutopilotListJobsParams",
-    "AutopilotGetJobParams",
-    "JobCreateParams",
-    "JobStatusParams",
-    "JobPauseParams",
-    "JobResumeParams",
-    "JobCancelParams",
-    "JobDagParams",
-    "JobGuidanceParams",
-    "CronAddParams",
-    "CronListParams",
-    "CronShowParams",
-    "CronCancelParams",
-    "DaemonStatusParams",
-    "DaemonShutdownParams",
-    "ConfigGetParams",
-    "ConfigReloadParams",
-    "SkillsListParams",
-    "ModelsListParams",
-    "InvokeSkillParams",
-    "McpStatusParams",
-    "AuthParams",
-    "AuthRefreshParams",
-    "SlashCommandParams",
-    "RpcCommandParams",
-    "DisconnectParams",
-]