soothe-cli 0.1.0__py3-none-any.whl

soothe_cli/shared/message_processing.py

@@ -0,0 +1,393 @@
+"""Shared message processing utilities for CLI and TUI modes.
+
+This module provides helper functions for message handling logic to ensure
+consistent behavior between headless CLI mode and the TUI interface.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import re
+from typing import Any
+
+from soothe_sdk.internal import strip_internal_tags  # noqa: F401 — re-exported via shared.__init__
+
+# ============================================================================
+# Shared Tool Call Streaming Helpers (IG-053)
+# ============================================================================
+
+
+def accumulate_tool_call_chunks(
+    pending_tool_calls: dict[str, dict[str, Any]],
+    tool_call_chunks: list[dict[str, Any]],
+    *,
+    is_main: bool = True,
+) -> None:
+    """Accumulate streaming tool call chunks into pending_tool_calls.
+
+    LangChain streams tool args in chunks - first chunk has the tool name but
+    empty args, subsequent chunks contain partial JSON strings. This function
+    tracks and accumulates them.
+
+    Args:
+        pending_tool_calls: Dict to store pending tool calls (tool_call_id -> state).
+        tool_call_chunks: List of tool_call_chunk dicts from AIMessageChunk.
+        is_main: Whether this is from the main agent.
+    """
+    for tcc in tool_call_chunks:
+        if not isinstance(tcc, dict):
+            continue
+        tc_id = tcc.get("id", "")
+        tc_name = tcc.get("name")
+        tc_args = tcc.get("args", "")
+
+        # First chunk with a tool name: register the pending tool call
+        if tc_name and tc_id and tc_id not in pending_tool_calls:
+            pending_tool_calls[tc_id] = {
+                "name": tc_name,
+                "args_str": tc_args if isinstance(tc_args, str) else "",
+                "emitted": False,
+                "is_main": is_main,
+            }
+        # Subsequent chunks: accumulate args
+        elif tc_args and isinstance(tc_args, str):
+            # Find the tool call to accumulate args for (by order, first non-emitted)
+            for pending in pending_tool_calls.values():
+                if not pending["emitted"]:
+                    pending["args_str"] += tc_args
+                    break
+
+
+def try_parse_pending_tool_call_args(
+    pending: dict[str, Any],
+) -> dict[str, Any] | None:
+    """Try to parse the accumulated args_str as JSON.
+
+    Args:
+        pending: Pending tool call state dict with 'args_str' key.
+
+    Returns:
+        Parsed args dict if valid JSON, None otherwise.
+    """
+    args_str = pending.get("args_str", "")
+    if not args_str:
+        return None
+    try:
+        parsed = json.loads(args_str)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+def finalize_pending_tool_call(
+    pending_tool_calls: dict[str, dict[str, Any]],
+    tool_call_id: str,
+) -> tuple[dict[str, Any] | None, dict[str, Any], bool, str]:
+    """Finalize and remove a pending tool call when its result arrives.
+
+    Args:
+        pending_tool_calls: Dict of pending tool calls.
+        tool_call_id: ID of the tool call to finalize.
+
+    Returns:
+        Tuple of (parsed_args, pending_state dict, needs_emit, raw_args_str).
+        - parsed_args: Parsed args dict if valid JSON, None otherwise.
+        - pending_state: The pending tool call state dict.
+        - needs_emit: True if the tool call wasn't emitted yet.
+        - raw_args_str: Raw args string for display fallback.
+        If not found, returns (None, {}, False, "").
+    """
+    str_id = str(tool_call_id) if tool_call_id else ""
+    if not str_id or str_id not in pending_tool_calls:
+        return None, {}, False, ""
+
+    pending = pending_tool_calls[str_id]
+    parsed_args = None
+    needs_emit = not pending.get("emitted", False)
+    raw_args_str = pending.get("args_str", "")
+
+    if needs_emit:
+        # Try to parse args one more time
+        if raw_args_str:
+            with contextlib.suppress(json.JSONDecodeError):
+                result = json.loads(raw_args_str)
+                if isinstance(result, dict):
+                    parsed_args = result
+        pending["emitted"] = True
+
+    # Clean up the pending entry
+    del pending_tool_calls[str_id]
+    return parsed_args, pending, needs_emit, raw_args_str
+
+
+def extract_tool_brief(tool_name: str, content: str | dict | Any, max_length: int = 120) -> str:
+    r"""Extract a concise one-line summary from tool result content.
+
+    Uses semantic formatters to provide tool-specific summaries with meaningful
+    metrics (size, count, status) instead of simple truncation.
+
+    Args:
+        tool_name: Name of the tool that produced the content.
+        content: Tool result content (string, dict, or ToolOutput).
+        max_length: Maximum length of the brief (default 120, unused for semantic formatting).
+
+    Returns:
+        Semantic brief suitable for display.
+
+    Example:
+        >>> extract_tool_brief("read_file", "Hello\\nWorld\\n")
+        "✓ Read 12 B (2 lines)"
+        >>> extract_tool_brief("run_command", "output")
+        "✓ Done (6 chars output)"
+    """
+    # Use semantic formatter for tool-specific summarization
+    from soothe_cli.shared.tool_output_formatter import ToolOutputFormatter
+
+    try:
+        formatter = ToolOutputFormatter()
+        brief = formatter.format(tool_name, content)
+        return brief.to_display()
+    except Exception:
+        # Fallback to simple truncation if formatter fails
+        if isinstance(content, str):
+            # Web search/crawl tools return structured output with summary on first line
+            web_tools = {"search_web", "crawl_web"}
+            if tool_name in web_tools:
+                first_line = content.split("\n", 1)[0].strip()
+                if first_line:
+                    return first_line[:max_length]
+            return content.replace("\n", " ")[:max_length]
+        if isinstance(content, dict):
+            # Simple dict formatting
+            return f"Dict with {len(content)} fields"
+        return str(content)[:max_length]
+
+
+def coerce_tool_call_args_to_dict(raw: Any) -> dict[str, Any]:
+    """Normalize tool arguments for display.
+
+    ``tool_call_chunk`` content blocks use a JSON string; merged ``tool_calls`` use dicts
+    (see LangChain ``ToolCall`` / ``ToolCallChunk``).
+    """
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str):
+        s = raw.strip()
+        if not s:
+            return {}
+        try:
+            parsed = json.loads(s)
+        except json.JSONDecodeError:
+            return {}
+        if isinstance(parsed, dict):
+            return parsed
+        return {}
+    return {}
+
+
+def coerce_tool_call_entry_to_dict(tc: Any) -> dict[str, Any] | None:
+    """Normalize a ``tool_calls`` entry to a plain dict (handles Pydantic models)."""
+    if isinstance(tc, dict):
+        return tc
+    model_dump = getattr(tc, "model_dump", None)
+    if callable(model_dump):
+        try:
+            dumped = model_dump()
+            if isinstance(dumped, dict):
+                return dumped
+        except Exception:
+            return None
+    return None
+
+
+def normalize_tool_calls_list(raw: list[Any]) -> list[dict[str, Any]]:
+    """Coerce ``msg.tool_calls`` to ``dict`` entries for display logic."""
+    out: list[dict[str, Any]] = []
+    for tc in raw:
+        coerced = coerce_tool_call_entry_to_dict(tc)
+        if coerced:
+            out.append(coerced)
+    return out
+
+
+def tool_calls_have_any_arg_dict(tc_list: list[Any]) -> bool:
+    """True if any tool call has non-empty coerced argument dict."""
+    return any(
+        coerce_tool_call_args_to_dict(tc.get("args")) for tc in normalize_tool_calls_list(tc_list)
+    )
+
+
+# Argument display mapping for tool calls (see IG-053)
+# Maps tool name to list of argument keys to display (supports multiple args)
+_ARG_DISPLAY_MAP: dict[str, list[str]] = {
+    # File operations — deepagents uses ``file_path`` for read/write/edit (see IG-053)
+    "read_file": ["file_path", "path"],
+    "write_file": ["file_path", "path"],
+    "delete_file": ["file_path", "path"],
+    "file_info": ["path", "file_path"],
+    "edit_file_lines": ["path", "file_path"],
+    "insert_lines": ["path", "file_path"],
+    "delete_lines": ["path", "file_path"],
+    "apply_diff": ["path", "file_path"],
+    "edit_file": ["file_path", "path"],
+    "ls": ["path", "pattern"],  # Multiple args support
+    "glob": ["pattern", "path"],  # Glob tool
+    "list_files": ["pattern"],
+    "search_files": ["pattern"],
+    # Execution - show command/code
+    "run_command": ["command", "args"],  # Multiple args support
+    "run_python": ["code"],
+    "run_background": ["command"],
+    "kill_process": ["pid"],
+    "execute": ["command"],  # Alias for run_command
+    # Search - show pattern/query
+    "search_web": ["query"],
+    "crawl_web": ["url"],
+    # Research - show topic
+    "research": ["topic", "domain"],
+    # Media - show file path
+    "analyze_image": ["image_path"],
+    "analyze_video": ["video_path"],
+    "transcribe_audio": ["audio_path"],
+    # Goals - show description or ID
+    "create_goal": ["description"],
+    "complete_goal": ["goal_id"],
+    "fail_goal": ["goal_id"],
+}
+
+
+def _normalize_tool_name_for_arg_map(tool_name: str) -> str:
+    """Map API tool names (any casing) to snake_case for `_ARG_DISPLAY_MAP` lookup."""
+    if not tool_name:
+        return tool_name
+    # PascalCase / camelCase -> snake_case; already-snake names pass through
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", tool_name).lower()
+
+
+def format_tool_call_args(tool_name: str, tool_call: dict[str, Any]) -> str:
+    """Format key tool arguments for display (see IG-053).
+
+    Extracts the most relevant argument(s) for each tool type to show
+    in activity events. Supports multiple arguments per tool.
+
+    Path arguments are converted from deepagents workspace-relative format
+    to actual OS paths and abbreviated for display.
+
+    Args:
+        tool_name: Tool name as emitted by the model (snake_case or PascalCase).
+        tool_call: Tool call dict with 'args' key containing arguments.
+            May also contain '_raw' key with raw args string for fallback display.
+
+    Returns:
+        Formatted argument string like "file_name.md" or "/Users/dev/.../file.md, pattern"
+        (without outer parentheses - caller adds them).
+        Returns "..." when args are empty but tool is known.
+        Returns "" if tool is unknown and no args.
+
+    Examples:
+        >>> format_tool_call_args("read_file", {"args": {"path": "config.yml"}})
+        'config.yml'
+        >>> format_tool_call_args("run_command", {"args": {"command": "ls", "args": "-la"}})
+        'ls, -la'
+        >>> format_tool_call_args("read_file", {"args": {}})
+        '...'
+        >>> format_tool_call_args("read_file", {"args": {}, "_raw": '{"path": "file.txt"}'})
+        'file.txt'
+    """
+    from soothe_sdk import convert_and_abbreviate_path, is_path_argument
+
+    max_value_length = 40  # Max length for displayed values
+
+    args = coerce_tool_call_args_to_dict(tool_call.get("args"))
+    internal = _normalize_tool_name_for_arg_map(tool_name)
+    key_args = _ARG_DISPLAY_MAP.get(internal)
+
+    # Check for raw args string fallback
+    raw_args_str = tool_call.get("_raw") or tool_call.get("raw_args_str", "")
+
+    # If args are empty, try to extract from raw args string
+    if not args and raw_args_str:
+        # Try to parse raw string as JSON
+        with contextlib.suppress(json.JSONDecodeError):
+            parsed_raw = json.loads(raw_args_str)
+            if isinstance(parsed_raw, dict):
+                args = parsed_raw
+
+    # If args are still empty but tool is known, show placeholder
+    if not args:
+        if key_args:
+            # Try to extract value from partial raw args string
+            if raw_args_str:
+                # Try regex extraction for common patterns like "path": "value" or "path":"value"
+                for key_arg in key_args:
+                    # Match patterns like "key": "value" or "key":"value"
+                    pattern = '"' + key_arg + '"\\s*:\\s*"([^"]+)"'
+                    match = re.search(pattern, raw_args_str)
+                    if match:
+                        value = match.group(1)
+                        if is_path_argument(key_arg):
+                            value = convert_and_abbreviate_path(value, max_length=max_value_length)
+                        return value
+                    # Also match non-string values like "key": 123 or "key": true
+                    pattern2 = '"' + key_arg + '"\\s*:\\s*([^,\\}]+)'
+                    match2 = re.search(pattern2, raw_args_str)
+                    if match2:
+                        val = match2.group(1).strip()
+                        # Truncate if too long
+                        if len(val) > max_value_length:
+                            val = val[: max_value_length - 3] + "..."
+                        return val
+            return "..."
+        return ""
+
+    if not key_args:
+        return ""
+
+    # Extract values for all configured argument keys
+    values = []
+    for key_arg in key_args:
+        if key_arg in args:
+            value = str(args[key_arg])
+            # Convert and abbreviate path arguments
+            if is_path_argument(key_arg):
+                value = convert_and_abbreviate_path(value, max_value_length)
+            elif len(value) > max_value_length:
+                # Truncate non-path long values
+                value = value[: max_value_length - 3] + "..."
+            values.append(value)
+
+    if not values:
+        # Model may use different arg names than _ARG_DISPLAY_MAP; still show something useful.
+        if args:
+            parts: list[str] = []
+            # Skip internal keys like _raw, _internal, etc.
+            skip_keys = {"_raw", "_internal", "raw_args_str"}
+            for k, v in list(args.items())[:3]:
+                if k in skip_keys:
+                    continue
+                s = str(v)
+                # Convert and abbreviate path arguments
+                if is_path_argument(k):
+                    s = convert_and_abbreviate_path(s, max_value_length)
+                elif len(s) > max_value_length:
+                    s = s[: max_value_length - 3] + "..."
+                parts.append(s)
+            if parts:
+                return ", ".join(parts)
+            # All args were internal keys, check for raw_args_str
+            raw = args.get("_raw") or args.get("raw_args_str", "")
+            if raw:
+                # Try to extract from raw JSON
+                for key_arg in key_args:
+                    pattern = '"' + key_arg + '"\\s*:\\s*"([^"]+)"'
+                    match = re.search(pattern, raw)
+                    if match:
+                        value = match.group(1)
+                        if is_path_argument(key_arg):
+                            value = convert_and_abbreviate_path(value, max_value_length)
+                        return value
+        # Known tool but no matching args found
+        return "..."
+
+    return ", ".join(values)

soothe_cli/shared/presentation_engine.py

@@ -0,0 +1,173 @@
+"""Unified presentation decisions for CLI/TUI surfaces.
+
+This module centralizes display-time suppression and summarization rules so
+renderers stay focused on output transport (stdout/stderr or widgets).
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+
+from soothe_sdk import log_preview
+from soothe_sdk.verbosity import VerbosityTier, should_show
+
+from soothe_cli.shared.display_policy import VerbosityLevel
+
+
+@dataclass
+class PresentationState:
+    """Stateful suppression metadata for presentation decisions."""
+
+    last_reason_key: str = ""
+    last_reason_at_s: float = 0.0
+    last_reason_by_step: dict[str, float] | None = None
+    final_answer_locked: bool = False
+
+    # Action deduplication tracking (IG-143)
+    last_action_text: str = ""
+    last_action_time: float = 0.0
+
+    def __post_init__(self) -> None:
+        """Initialize mutable map defaults safely."""
+        if self.last_reason_by_step is None:
+            self.last_reason_by_step = {}
+
+
+class PresentationEngine:
+    """Small policy engine for presentation-specific decisions."""
+
+    _REASON_DEDUP_WINDOW_S = 8.0
+    _REASON_STEP_RATE_LIMIT_S = 5.0
+    _TOOL_RESULT_MAX_CHARS = 180
+    _ACTION_DEDUP_WINDOW_S = 5.0
+
+    def __init__(self) -> None:
+        """Initialize presentation state."""
+        self._state = PresentationState()
+
+    @property
+    def final_answer_locked(self) -> bool:
+        """True after a custom final/chitchat response was emitted for this turn."""
+        return self._state.final_answer_locked
+
+    def mark_final_answer_locked(self) -> None:
+        """Record that the final user-visible answer was already emitted (e.g. custom event)."""
+        self._state.final_answer_locked = True
+
+    def reset_turn(self) -> None:
+        """Clear per-turn presentation state (reason dedup, final lock, action dedup)."""
+        self._state.last_reason_key = ""
+        self._state.last_reason_at_s = 0.0
+        self._state.last_reason_by_step.clear()
+        self._state.final_answer_locked = False
+        self._state.last_action_text = ""
+        self._state.last_action_time = 0.0
+
+    def reset_session(self) -> None:
+        """Clear presentation state for a new session (e.g. thread change)."""
+        self.reset_turn()
+
+    def tier_visible(self, tier: VerbosityTier, verbosity: VerbosityLevel) -> bool:
+        """Return whether content at the given verbosity tier should display."""
+        return should_show(tier, verbosity)
+
+    def should_emit_reason(
+        self,
+        *,
+        content: str,
+        step_id: str | None = None,
+        now_s: float | None = None,
+    ) -> bool:
+        """Decide whether a reason line should be emitted.
+
+        Applies short-window de-duplication and per-step rate limiting.
+        """
+        now = now_s if now_s is not None else time.monotonic()
+        normalized = self._normalize_reason(content)
+        if not normalized:
+            return False
+
+        # Global dedup window for near-identical reason updates.
+        if (
+            normalized == self._state.last_reason_key
+            and (now - self._state.last_reason_at_s) < self._REASON_DEDUP_WINDOW_S
+        ):
+            return False
+
+        # Per-step rate limit for noisy repeated updates.
+        if step_id:
+            last_step_at = self._state.last_reason_by_step.get(step_id, 0.0)
+            if (now - last_step_at) < self._REASON_STEP_RATE_LIMIT_S:
+                return False
+            self._state.last_reason_by_step[step_id] = now
+
+        self._state.last_reason_key = normalized
+        self._state.last_reason_at_s = now
+        return True
+
+    def summarize_tool_result(self, text: str) -> str:
+        """Convert noisy tool results into concise one-line summaries."""
+        compact = " ".join(text.split())
+        if not compact:
+            return compact
+
+        # If payload looks like a huge list/dict dump, replace with a compact marker.
+        if (compact.startswith("[") and compact.endswith("]")) or (
+            compact.startswith("{") and compact.endswith("}")
+        ):
+            return "Tool result received (structured payload)."
+
+        return log_preview(compact, self._TOOL_RESULT_MAX_CHARS)
+
+    @staticmethod
+    def _normalize_reason(content: str) -> str:
+        lowered = content.lower().strip()
+        lowered = re.sub(r"\(\d+%\s+sure\)", "", lowered)
+        return re.sub(r"\s+", " ", lowered)
+
+    def should_emit_action(
+        self,
+        *,
+        action_text: str,
+        now_s: float | None = None,
+    ) -> bool:
+        """Deduplicate repeated action summaries within 5s window.
+
+        Args:
+            action_text: Action summary text (may include confidence).
+            now_s: Optional timestamp (defaults to monotonic time).
+
+        Returns:
+            True if action should be emitted, False if duplicate.
+        """
+        normalized = self._normalize_action(action_text)
+        now = now_s if now_s is not None else time.monotonic()
+
+        # Dedup identical actions within window
+        if (
+            normalized == self._state.last_action_text
+            and (now - self._state.last_action_time) < self._ACTION_DEDUP_WINDOW_S
+        ):
+            return False
+
+        # Update state
+        self._state.last_action_text = normalized
+        self._state.last_action_time = now
+        return True
+
+    @staticmethod
+    def _normalize_action(text: str) -> str:
+        """Strip confidence and whitespace for action comparison.
+
+        Args:
+            text: Action text to normalize.
+
+        Returns:
+            Normalized text for deduplication comparison.
+        """
+        lowered = text.lower().strip()
+        # Remove "(XX% sure)" or "(XX% confident)" suffix
+        lowered = re.sub(r"\(\d+%\s+(?:sure|confident)\)", "", lowered)
+        return re.sub(r"\s+", " ", lowered)

soothe_cli/shared/processor_state.py

@@ -0,0 +1,80 @@
+"""Processor state for unified event handling.
+
+This module defines the internal state managed by EventProcessor.
+Renderers should not modify this state directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from soothe_sdk import Plan
+
+
+@dataclass
+class ProcessorState:
+    """Internal state for EventProcessor.
+
+    This state is owned by the processor and should not be
+    modified directly by renderers. Renderers can read state
+    via processor properties.
+    """
+
+    # Message deduplication - tracks seen message IDs
+    seen_message_ids: set[str] = field(default_factory=set)
+
+    # Streaming tool call arg accumulation (IG-053)
+    # Maps tool_call_id -> {'name': str, 'args_str': str, 'emitted': bool, 'is_main': bool}
+    pending_tool_calls: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    # Namespace -> display name mapping for subagents
+    name_map: dict[str, str] = field(default_factory=dict)
+
+    # Current plan state (updated on plan events)
+    current_plan: Plan | None = None
+
+    # Thread identifier from daemon
+    thread_id: str = ""
+
+    # Multi-step plan suppression flag (suppress step text, show final report)
+    multi_step_active: bool = False
+
+    # Internal context tracking (suppress internal LLM responses)
+    internal_context_active: bool = False
+
+    # Tool call timing for duration display (RFC-0020)
+    # Maps tool_call_id -> start_timestamp
+    tool_call_start_times: dict[str, float] = field(default_factory=dict)
+
+    # Deduplication for tool calls (prevents duplicate display)
+    emitted_tool_call_ids: set[str] = field(default_factory=set)
+
+    # Deduplication for tool results (prevents duplicate display)
+    emitted_tool_result_ids: set[str] = field(default_factory=set)
+
+    def reset_turn(self) -> None:
+        """Reset per-turn state.
+
+        Called when a turn ends (status becomes idle/stopped).
+        Clears streaming buffers but preserves session state.
+        """
+        self.pending_tool_calls.clear()
+        self.tool_call_start_times.clear()
+        self.emitted_tool_call_ids.clear()
+        self.emitted_tool_result_ids.clear()
+
+    def clear_session(self) -> None:
+        """Clear all session state.
+
+        Called when thread changes. Resets everything for fresh session.
+        """
+        self.seen_message_ids.clear()
+        self.pending_tool_calls.clear()
+        self.current_plan = None
+        self.multi_step_active = False
+        self.internal_context_active = False
+        self.tool_call_start_times.clear()
+        self.emitted_tool_call_ids.clear()
+        self.emitted_tool_result_ids.clear()