soothe-client-python 1.0.24__py3-none-any.whl → 1.2.0__py3-none-any.whl

soothe_client/__init__.py

@@ -11,8 +11,6 @@ from __future__ import annotations
 
 import importlib.metadata
 
-from soothe_sdk.wire.codec import ProtocolError
-
 from soothe_client.command_client import (
     AsyncCommandClient,
     CommandClient,
@@ -52,6 +50,7 @@ from soothe_client.session import (
     connect_websocket_with_retries,
 )
 from soothe_client.websocket import WebSocketClient
+from soothe_client.wire.codec import ProtocolError
 
 try:
     __version__ = importlib.metadata.version("soothe-client-python")

soothe_client/appkit/card_projection.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from soothe_sdk.display.card_wire import CardProjection, parse_card_custom_payload
+from soothe_client.display.card_wire import CardProjection, parse_card_custom_payload
 
 __all__ = [
     "CardProjection",

soothe_client/appkit/chunk_filter.py

@@ -61,8 +61,17 @@ def _plain_text(msg: dict[str, Any]) -> str:
     return ""
 
 
+def _dict_has_reasoning_content(msg: dict[str, Any]) -> bool:
+    """True when a wire message dict carries captured reasoning in ``additional_kwargs``."""
+    body = _wire_body(msg)
+    ak = body.get("additional_kwargs")
+    if not isinstance(ak, dict):
+        return False
+    return bool(str(ak.get("reasoning_content") or "").strip())
+
+
 def message_chunk_is_non_actionable(data: Any) -> bool:
-    """True when a wire `messages` pair has no tool, text, or loop phase payload."""
+    """True when a wire `messages` pair has no tool, text, reasoning, or loop phase payload."""
     if not isinstance(data, (list, tuple)) or len(data) != _MSG_PAIR_LEN:
         return False
     msg = data[0]
@@ -79,6 +88,8 @@ def message_chunk_is_non_actionable(data: Any) -> bool:
         return False
     if body.get("phase") or msg.get("phase"):
         return False
+    if _dict_has_reasoning_content(msg):
+        return False
     return not _plain_text(msg).strip()
 
 
@@ -93,6 +104,7 @@ def should_drop_stream_chunk_early(namespace: tuple[Any, ...], mode: str, data:
 
 
 __all__ = [
+    "_dict_has_reasoning_content",
     "message_chunk_is_non_actionable",
     "should_drop_stream_chunk_early",
     "updates_chunk_is_noop",

soothe_client/appkit/managed_client.py

@@ -47,7 +47,7 @@ _REQUEST_METHOD_ALIASES = {
 
 def _coerce_appkit_wire_message(msg: dict[str, Any], client: WebSocketClient) -> dict[str, Any]:
     """Upgrade flat appkit dicts to protocol-1 envelopes when needed."""
-    from soothe_sdk.wire.codec import MessageType, WireEnvelope
+    from soothe_client.wire.codec import MessageType, WireEnvelope
 
     msg_type = str(msg.get("type") or "")
     if msg.get("proto") == "1" or msg_type in _ALREADY_ENVELOPE_TYPES:

soothe_client/appkit/turn.py

@@ -14,7 +14,7 @@ import time
 from collections.abc import AsyncIterator, Callable
 from typing import Any, Generic, Protocol, TypeVar
 
-from soothe_sdk.ux.loop_stream import assistant_output_phase
+from soothe_client.ux.loop_stream import assistant_output_phase
 
 logger = logging.getLogger(__name__)
 

soothe_client/command_client.py

@@ -10,7 +10,8 @@ import logging
 from typing import Any, cast
 from uuid import uuid4
 
-from soothe_sdk.wire.codec import (
+from soothe_client.helpers import websocket_url_from_config
+from soothe_client.wire.codec import (
     ConnectionInitEnvelope,
     ConnectionInitParams,
     ErrorEnvelope,
@@ -20,8 +21,6 @@ from soothe_sdk.wire.codec import (
     encode_envelope,
 )
 
-from soothe_client.helpers import websocket_url_from_config
-
 logger = logging.getLogger(__name__)
 
 _TRANSITIONAL_DAEMON_READY_STATES = frozenset({"starting", "warming"})
@@ -34,7 +33,9 @@ _DAEMON_READY_POLL_INTERVAL_S = 0.05
 _DEFAULT_MAX_FRAME_SIZE = 10 * 1024 * 1024
 
 try:
-    from soothe_sdk import __version__ as _client_version
+    from importlib.metadata import version as _pkg_version
+
+    _client_version = _pkg_version("soothe-client-python")
 except Exception:  # pragma: no cover
     _client_version = "0.0.0"
 
@@ -82,7 +83,7 @@ async def _perform_handshake(ws: Any, *, timeout: float) -> None:
     init = ConnectionInitEnvelope(
         params=ConnectionInitParams(
             client_version=_client_version,
-            client_name="soothe-sdk",
+            client_name="soothe-client-python",
             accept_proto=["1"],
             capabilities=["streaming", "batch", "heartbeat"],
         )

soothe_client/core/__init__.py

@@ -0,0 +1 @@
+"""Client-side event contracts: wire event types, verbosity tiers, subagent wire helpers."""

soothe_client/core/events.py

@@ -0,0 +1,163 @@
+"""Base event classes for Soothe events.
+
+This module provides the base event classes that all specific events inherit from.
+Module-specific events are defined in their respective modules and registered via
+``register_event()``.
+
+Progress events use type strings ``soothe.<domain>.<component>.<action>``.
+Domains in active use include cognition, internal, subagent, system, mcp, loop,
+stream, error, tool, output, protocol, and skillify. Community plugins may
+introduce additional ``soothe.subagent.<plugin>.*`` types when they load.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SootheEvent(BaseModel):
+    """Base class for all Soothe progress events."""
+
+    type: str
+
+    model_config = ConfigDict(extra="allow")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict for wire-format emission."""
+        return self.model_dump(exclude_none=True)
+
+    def emit(self, logger: logging.Logger) -> None:
+        """Emit this event via the LangGraph stream writer.
+
+        Note: This method requires host-side implementation.
+        For SDK use, events are typically sent via WebSocket.
+
+        SDK-side event base class: provides type definition and serialization.
+        Host-side implementation provides actual emit.
+        """
+        pass
+
+
+class LifecycleEvent(SootheEvent):
+    """Loop and session lifecycle events."""
+
+
+class ProtocolEvent(SootheEvent):
+    """Core protocol activity events."""
+
+
+class SubagentEvent(SootheEvent):
+    """Subagent activity events."""
+
+
+class OutputEvent(SootheEvent):
+    """Content destined for user display."""
+
+
+class ErrorEvent(SootheEvent):
+    """Error events."""
+
+    error: str
+
+
+# Event type constants
+# Wire-safe event type strings for CLI/TUI event processing
+# Exposed at DEBUG and DETAILED level for fine-grained (per-turn) event display
+
+# Plan events
+PLAN_CREATED = "soothe.cognition.plan.created"
+
+# Agent loop events (DEBUG level; wire ``mode=custom`` types)
+STRANGE_LOOP_STARTED = "soothe.cognition.strange_loop.started"
+STRANGE_LOOP_COMPLETED = "soothe.cognition.strange_loop.completed"
+STRANGE_LOOP_STEP_STARTED = "soothe.cognition.strange_loop.step.started"
+STRANGE_LOOP_STEP_QUEUED = "soothe.cognition.strange_loop.step.queued"
+STRANGE_LOOP_STEP_COMPLETED = "soothe.cognition.strange_loop.step.completed"
+STRANGE_LOOP_PLAN_DECISION = "soothe.cognition.strange_loop.plan.decision"
+STRANGE_LOOP_PLAN_PHASE = "soothe.cognition.strange_loop.plan.phase"
+# Wired specialist lifecycle (orphan SubAgent card)
+WIRED_SUBAGENT_STARTED = "soothe.cognition.wired_subagent.started"
+WIRED_SUBAGENT_COMPLETED = "soothe.cognition.wired_subagent.completed"
+WIRED_SUBAGENT_FAILED = "soothe.cognition.wired_subagent.failed"
+WIRED_SUBAGENT_CANCELLED = "soothe.cognition.wired_subagent.cancelled"
+INTENT_CLASSIFIED = "soothe.cognition.intent.classified"
+
+# Clarification relay events
+LOOP_CLARIFICATION_REQUESTED = "soothe.loop.clarification.requested"
+LOOP_CLARIFICATION_ANSWERED = "soothe.loop.clarification.answered"
+LOOP_CLARIFICATION_DEFERRED = "soothe.loop.clarification.deferred"
+
+# Stream termination
+STREAM_END = "soothe.stream.end"
+
+# Display card wire frames (RFC-413) — top-level or ``event``/``custom`` ``data.type``
+CARD_CREATED = "soothe.card.created"
+CARD_UPDATED = "soothe.card.updated"
+CARD_FINALIZED = "soothe.card.finalized"
+CARD_REPLAY_BEGIN = "soothe.card.replay.begin"
+CARD_REPLAY_END = "soothe.card.replay.end"
+CARD_WIRE_TYPES = frozenset({CARD_CREATED, CARD_UPDATED, CARD_FINALIZED})
+CARD_REPLAY_WIRE_TYPES = frozenset({CARD_REPLAY_BEGIN, CARD_REPLAY_END})
+
+# Protocol-primitive events (wire-visible constants shared across packages;
+# canonical home is the SDK as the protocol-contracts layer. nano and the
+# host re-export these rather than redefine the literals.)
+ERROR = "soothe.error.general.failed"
+LLM_RETRY_ATTEMPT = "soothe.cognition.llm.retry.attempt"
+MEMORY_RECALLED = "soothe.internal.memory.recalled"
+MEMORY_STORED = "soothe.internal.memory.stored"
+POLICY_CHECKED = "soothe.internal.policy.checked"
+POLICY_DENIED = "soothe.internal.policy.denied"
+
+# Agent loop configuration constants
+DEFAULT_STRANGE_LOOP_MAX_ITERATIONS = 10
+
+
+__all__ = [
+    "ErrorEvent",
+    "LifecycleEvent",
+    "OutputEvent",
+    "ProtocolEvent",
+    "SootheEvent",
+    "SubagentEvent",
+    # Event type constants - plan
+    "PLAN_CREATED",
+    # Agent loop (DEBUG)
+    "STRANGE_LOOP_STARTED",
+    "STRANGE_LOOP_COMPLETED",
+    "STRANGE_LOOP_STEP_STARTED",
+    "STRANGE_LOOP_STEP_QUEUED",
+    "STRANGE_LOOP_STEP_COMPLETED",
+    "STRANGE_LOOP_PLAN_DECISION",
+    "STRANGE_LOOP_PLAN_PHASE",
+    "WIRED_SUBAGENT_STARTED",
+    "WIRED_SUBAGENT_COMPLETED",
+    "WIRED_SUBAGENT_FAILED",
+    "WIRED_SUBAGENT_CANCELLED",
+    "INTENT_CLASSIFIED",
+    # Clarification relay
+    "LOOP_CLARIFICATION_REQUESTED",
+    "LOOP_CLARIFICATION_ANSWERED",
+    "LOOP_CLARIFICATION_DEFERRED",
+    "STREAM_END",
+    # Display card wire (RFC-413)
+    "CARD_CREATED",
+    "CARD_UPDATED",
+    "CARD_FINALIZED",
+    "CARD_REPLAY_BEGIN",
+    "CARD_REPLAY_END",
+    "CARD_WIRE_TYPES",
+    "CARD_REPLAY_WIRE_TYPES",
+    # Protocol-primitive constants (canonical home; re-exported by nano + host)
+    "ERROR",
+    "LLM_RETRY_ATTEMPT",
+    "MEMORY_RECALLED",
+    "MEMORY_STORED",
+    "POLICY_CHECKED",
+    "POLICY_DENIED",
+    # Constants
+    "DEFAULT_STRANGE_LOOP_MAX_ITERATIONS",
+]

soothe_client/core/subagent_wire.py

@@ -0,0 +1,141 @@
+"""Curated ``soothe.subagent.*`` wire protocol (metadata-only).
+
+Provides registration, structural validation, payload clipping, and stream emission.
+Event type strings live in each subagent (or plugin) ``events`` module — not in this SDK.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+_REGISTERED_SUBAGENT_WIRE_TYPES: set[str] = set()
+
+# ``soothe.subagent.<agent>.<signal>`` — clients may accept before producers register types.
+_CURATED_SUBAGENT_WIRE_RE = re.compile(r"^soothe\.subagent\.[a-z][a-z0-9_]*\.[a-z][a-z0-9_.]+$")
+
+_DEFAULT_PREVIEW_LEN = 120
+_LONG_PREVIEW_LEN = 200
+_TASK_DESCRIPTION_LEN = 8000
+
+
+def register_subagent_wire_event_types(*event_types: str) -> None:
+    """Register ``soothe.subagent.*`` wire types for emission allowlisting.
+
+    Subagents call this from their ``events`` module (or rely on the host
+    event registry to register automatically).
+    """
+    for et in event_types:
+        if isinstance(et, str) and et.startswith("soothe.subagent."):
+            _REGISTERED_SUBAGENT_WIRE_TYPES.add(et)
+
+
+def get_allowlisted_subagent_event_types() -> frozenset[str]:
+    """Return wire types registered for emission in this process."""
+    return frozenset(_REGISTERED_SUBAGENT_WIRE_TYPES)
+
+
+def is_curated_subagent_wire_event_type(event_type: str) -> bool:
+    """Return True for structurally valid curated ``soothe.subagent.*`` wire types.
+
+    Used by CLI/TUI clients that may not import subagent ``events`` modules.
+    """
+    return bool(_CURATED_SUBAGENT_WIRE_RE.match(event_type))
+
+
+def is_emit_allowed_subagent_wire_event_type(event_type: str) -> bool:
+    """Return True when a producer may emit this subagent wire event."""
+    return event_type in _REGISTERED_SUBAGENT_WIRE_TYPES
+
+
+def is_allowlisted_subagent_event_type(event_type: str) -> bool:
+    """Return True when a consumer may treat ``event_type`` as curated subagent wire."""
+    return is_emit_allowed_subagent_wire_event_type(
+        event_type
+    ) or is_curated_subagent_wire_event_type(event_type)
+
+
+def parse_subagent_wire_agent(event_type: str) -> str | None:
+    """Return agent segment (``browser``, ``claude``, …) from ``soothe.subagent.<agent>.…``."""
+    parts = event_type.split(".")
+    if len(parts) >= 4 and parts[0] == "soothe" and parts[1] == "subagent":
+        return parts[2]
+    return None
+
+
+def truncate_wire_str(value: str, max_len: int = _DEFAULT_PREVIEW_LEN) -> str:
+    """Truncate a single wire string field."""
+    if len(value) <= max_len:
+        return value
+    if max_len <= 1:
+        return "…"
+    return value[: max_len - 1] + "…"
+
+
+def clip_wire_event_payload(data: dict[str, Any]) -> dict[str, Any]:
+    """Copy event dict and truncate known string fields for wire safety."""
+    out = dict(data)
+    string_caps: dict[str, int] = {
+        "task_preview": _LONG_PREVIEW_LEN,
+        "topic": _LONG_PREVIEW_LEN,
+        "topic_preview": _DEFAULT_PREVIEW_LEN,
+        "search_target": _TASK_DESCRIPTION_LEN,
+        "task": _LONG_PREVIEW_LEN,
+        "judgement": _LONG_PREVIEW_LEN,
+        "message": _LONG_PREVIEW_LEN,
+        "error": _LONG_PREVIEW_LEN,
+        "action_preview": _DEFAULT_PREVIEW_LEN,
+        "tool_name": _DEFAULT_PREVIEW_LEN,
+        "input_preview": _DEFAULT_PREVIEW_LEN,
+        "summary": _LONG_PREVIEW_LEN,
+        "url": _LONG_PREVIEW_LEN,
+        "title": _DEFAULT_PREVIEW_LEN,
+        "query_preview": _DEFAULT_PREVIEW_LEN,
+        "args_preview": _DEFAULT_PREVIEW_LEN,
+        "result_preview": _DEFAULT_PREVIEW_LEN,
+    }
+    for key, cap in string_caps.items():
+        val = out.get(key)
+        if isinstance(val, str):
+            out[key] = truncate_wire_str(val, cap)
+    return out
+
+
+def emit_subagent_wire_event(event: dict[str, Any], logger: logging.Logger) -> None:
+    """Emit allowlisted subagent progress to the LangGraph ``custom`` stream.
+
+    Community subagents use this helper so they do not depend on the host package.
+    Unknown event types are dropped unless registered via :func:`register_subagent_wire_event_types`.
+
+    Args:
+        event: Dict with at least ``type`` registered for emission.
+        logger: Caller logger for audit trail.
+    """
+    et = event.get("type", "")
+    if not isinstance(et, str) or not is_emit_allowed_subagent_wire_event_type(et):
+        logger.debug("Ignoring non-allowlisted subagent wire event: %r", et)
+        return
+    clipped = clip_wire_event_payload(event)
+    logger.debug("subagent.wire %s", clipped.get("type", ""))
+    try:
+        from langgraph.config import get_stream_writer
+
+        writer = get_stream_writer()
+        if writer:
+            writer(clipped)
+    except (ImportError, RuntimeError, KeyError):
+        pass
+
+
+__all__ = [
+    "clip_wire_event_payload",
+    "emit_subagent_wire_event",
+    "get_allowlisted_subagent_event_types",
+    "is_allowlisted_subagent_event_type",
+    "is_curated_subagent_wire_event_type",
+    "is_emit_allowed_subagent_wire_event_type",
+    "parse_subagent_wire_agent",
+    "register_subagent_wire_event_types",
+    "truncate_wire_str",
+]

soothe_client/core/verbosity.py

@@ -0,0 +1,49 @@
+"""Binary verbosity tier for event classification.
+
+Events classify to one of two tiers:
+- `NORMAL`: client-visible — flows over the wire to subscribed clients.
+- `INTERNAL`: hidden — daemon-side only, never leaves the daemon.
+
+Earlier revisions had a five-level ladder (QUIET / NORMAL / DETAILED / DEBUG /
+INTERNAL). That granularity was never exercised — the wire ceiling and the TUI
+gate were both hardcoded to "normal", so the only effective distinction was
+visible-vs-hidden. The tiers collapsed accordingly.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class VerbosityTier(IntEnum):
+    """Visibility class for catalog events.
+
+    `NORMAL` events are sent to clients; `INTERNAL` events are not.
+
+    Examples:
+        >>> should_show(VerbosityTier.NORMAL)
+        True
+        >>> should_show(VerbosityTier.INTERNAL)
+        False
+    """
+
+    NORMAL = 1
+    INTERNAL = 99
+
+
+def should_show(tier: VerbosityTier) -> bool:
+    """Return True if tier is client-visible.
+
+    Args:
+        tier: Visibility class of the content.
+
+    Returns:
+        True iff `tier` is `NORMAL`.
+    """
+    return tier == VerbosityTier.NORMAL
+
+
+__all__ = [
+    "VerbosityTier",
+    "should_show",
+]

soothe_client/display/__init__.py

@@ -0,0 +1,75 @@
+"""Client-side display-layer contract parsing.
+
+This package hosts the wire-protocol parse side shared by the transport,
+appkit, and any Python front end:
+
+* ``transcript_types`` — ``MessageData`` / ``MessageType`` / ``ToolStatus``
+  dataclasses travelling on the wire.
+* ``card_ledger`` — pure-Python ``CardMutation`` + ``InMemoryCardLedger``
+  primitives backing the ``soothe.card.*`` wire schema.
+* ``card_wire`` — parse/apply helpers for live ``soothe.card.*`` frames.
+* ``snapshot_types`` — goal display snapshot wire payload types.
+* ``message_processing`` / ``tool_result`` / ``tool_message_format`` —
+  stream-to-text parse helpers.
+
+(TUI-owned ``card_binder`` / ``text_extract`` / ``snapshot_collapser`` moved
+to `soothe_cli.display` / the host `soothe.display` in 1.2.0.)
+"""
+
+from __future__ import annotations
+
+from soothe_client.display.card_ledger import (
+    CARD_SCHEMA_VERSION,
+    CardMutation,
+    CardOp,
+    InMemoryCardLedger,
+    align_cards_preserving_ids,
+    build_header_mutation,
+    card_from_wire_dict,
+    card_to_wire_dict,
+    cards_to_mutations,
+    diff_card_snapshots,
+    utc_now_iso,
+)
+from soothe_client.display.card_wire import (
+    CardProjection,
+    parse_card_custom_payload,
+)
+from soothe_client.display.snapshot_types import (
+    GOAL_DISPLAY_SNAPSHOT_SCHEMA_VERSION,
+    GoalDisplaySnapshot,
+    snapshot_from_dataclass_dict,
+)
+from soothe_client.display.transcript_types import (
+    UPDATABLE_FIELDS,
+    MessageData,
+    MessageType,
+    ToolStatus,
+)
+
+__all__ = [
+    # Types
+    "MessageData",
+    "MessageType",
+    "ToolStatus",
+    "UPDATABLE_FIELDS",
+    # Ledger
+    "CARD_SCHEMA_VERSION",
+    "CardMutation",
+    "CardOp",
+    "InMemoryCardLedger",
+    "build_header_mutation",
+    "card_from_wire_dict",
+    "card_to_wire_dict",
+    "cards_to_mutations",
+    "diff_card_snapshots",
+    "align_cards_preserving_ids",
+    "utc_now_iso",
+    # Card wire
+    "CardProjection",
+    "parse_card_custom_payload",
+    # Goal display snapshots
+    "GOAL_DISPLAY_SNAPSHOT_SCHEMA_VERSION",
+    "GoalDisplaySnapshot",
+    "snapshot_from_dataclass_dict",
+]

soothe_client/display/_text_utils.py

@@ -0,0 +1,18 @@
+"""Internal text utilities for tool formatting (not part of public API)."""
+
+
+def text_looks_like_error(text: str) -> bool:
+    """Return True if text content suggests a tool failure.
+
+    Checks for common error indicator substrings.
+
+    Args:
+        text: Tool output text to inspect.
+
+    Returns:
+        True if any error indicator is found.
+    """
+    if not text:
+        return False
+    lowered = text.lower()
+    return any(indicator in lowered for indicator in ("error", "failed", "exception", "traceback"))