soothe-cli 0.1.0__py3-none-any.whl

soothe_cli/shared/suppression_state.py

@@ -0,0 +1,188 @@
+"""Shared suppression state for multi-step/agentic loop execution (IG-143).
+
+This module provides reusable state tracking and logic for suppressing
+intermediate output during multi-step plan execution and agentic loops.
+Both CLI and TUI renderers use this to prevent redundant intermediate output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from soothe_sdk.events import DEFAULT_AGENT_LOOP_MAX_ITERATIONS
+
+
+@dataclass
+class SuppressionState:
+    """Shared state for IG-143 multi-step/agentic suppression.
+
+    This tracks execution state to suppress intermediate LLM responses,
+    tool calls, and tool results during multi-step execution, showing
+    only essential progress events and the final aggregated report.
+
+    Usage:
+        # In renderer state:
+        suppression: SuppressionState = field(default_factory=SuppressionState)
+
+        # Check suppression:
+        if suppression.should_suppress_output():
+            return
+
+        # Track from events:
+        suppression.track_from_event(event_type, data)
+
+        # Get final report:
+        if suppression.should_emit_final_report(event_type, final_stdout):
+            text = suppression.get_final_response(final_stdout)
+            # ... emit text ...
+    """
+
+    # Multi-step plan suppression flag
+    multi_step_active: bool = False
+
+    # Agentic loop (max_iterations>1): keep suppressing until loop.completed
+    # even if status idle/on_turn_end cleared multi_step_active first
+    agentic_stdout_suppressed: bool = False
+
+    # Track if final stdout already emitted (prevent duplicate emission)
+    agentic_final_stdout_emitted: bool = False
+
+    # Accumulated response text for final report
+    full_response: list[str] = field(default_factory=list)
+
+    def should_suppress_output(self) -> bool:
+        """Check if output should be suppressed.
+
+        Returns:
+            True if multi-step or agentic loop is active and suppressing.
+        """
+        return self.multi_step_active or (
+            self.agentic_stdout_suppressed and not self.agentic_final_stdout_emitted
+        )
+
+    def should_emit_final_report(
+        self,
+        event_type: str,
+        final_stdout: str,
+    ) -> bool:
+        """Check if final report should be emitted on loop completion.
+
+        Args:
+            event_type: Event type string.
+            final_stdout: Final stdout message from event data.
+
+        Returns:
+            True if final report should be emitted.
+        """
+        if event_type != "soothe.cognition.agent_loop.completed":
+            return False
+
+        if not final_stdout:
+            return False
+
+        if self.agentic_final_stdout_emitted:
+            return False
+
+        # Mark flag when emitting
+        should_emit = self.multi_step_active or self.agentic_stdout_suppressed
+        if should_emit:
+            self.agentic_final_stdout_emitted = True
+
+        return should_emit
+
+    def track_from_event(self, event_type: str, data: dict) -> str:
+        """Track suppression state from progress event.
+
+        Args:
+            event_type: Event type string.
+            data: Event payload dict.
+
+        Returns:
+            Final stdout message if present (for emission after tracking).
+        """
+        # Track suppression state from agentic loop start.
+        # Suppress intermediate output only when max_iterations > 1 (multi-step mode).
+        # In single-step mode (max_iterations == 1), stdout flows normally and final_stdout
+        # should NOT be emitted separately to avoid duplication (IG-143 follow-up).
+        if event_type == "soothe.cognition.agent_loop.started":
+            max_iterations = data.get("max_iterations", DEFAULT_AGENT_LOOP_MAX_ITERATIONS)
+            if max_iterations > 1:
+                self.multi_step_active = True
+                self.agentic_stdout_suppressed = True
+                self.agentic_final_stdout_emitted = False
+
+        # Backup suppression: suppress after iteration 1+ if loop.started was filtered
+        if event_type == "soothe.cognition.agent_loop.reasoning":
+            try:
+                iteration = int(data.get("iteration", 0))
+            except (TypeError, ValueError):
+                iteration = 0
+            if iteration >= 1 and not self.agentic_final_stdout_emitted:
+                self.agentic_stdout_suppressed = True
+
+        # Extract final stdout message from loop completion
+        payload = dict(data)
+        final_stdout = (payload.pop("final_stdout_message", None) or "").strip()
+
+        # Note: agentic_final_stdout_emitted flag is set in should_emit_final_report()
+        # after checking the condition, not here (order matters for rendering logic)
+
+        return final_stdout
+
+    def track_from_plan(self, num_steps: int) -> None:
+        """Track suppression state from plan creation.
+
+        Args:
+            num_steps: Number of steps in the plan.
+        """
+        self.multi_step_active = num_steps > 1
+        # max_iterations==1 does not arm agentic_stdout_suppressed in loop.started;
+        # multi-step plans still clear multi_step_active on on_turn_end before
+        # loop.completed (test-case1).
+        if num_steps > 1:
+            self.agentic_stdout_suppressed = True
+            self.agentic_final_stdout_emitted = False
+
+    def get_final_response(self, final_stdout: str | None = None) -> str:
+        """Get accumulated final response text.
+
+        Args:
+            final_stdout: Optional final stdout message to append.
+
+        Returns:
+            Aggregated response text.
+        """
+        if final_stdout:
+            stripped = final_stdout.strip()
+            if stripped:
+                self.full_response.append(stripped)
+
+        # Join accumulated response
+        return "".join(self.full_response)
+
+    def accumulate_text(self, text: str) -> None:
+        """Accumulate text for final response.
+
+        Args:
+            text: Text chunk to accumulate.
+        """
+        self.full_response.append(text)
+
+    def reset_turn(self) -> None:
+        """Reset state for next turn.
+
+        Called on turn end (status becomes idle/stopped).
+        Clears suppression flags and accumulated response.
+        """
+        self.multi_step_active = False
+        self.full_response = []
+
+    def reset_session(self) -> None:
+        """Reset all session state.
+
+        Called when thread changes.
+        """
+        self.multi_step_active = False
+        self.agentic_stdout_suppressed = False
+        self.agentic_final_stdout_emitted = False
+        self.full_response = []

soothe_cli/shared/tool_formatters/__init__.py

@@ -0,0 +1,27 @@
+"""Tool-specific formatters for semantic result summarization.
+
+This package provides tool-specific formatters that transform raw tool outputs
+into concise, semantic summaries following RFC-0020 event display architecture.
+"""
+
+from __future__ import annotations
+
+from soothe_cli.shared.tool_formatters.base import BaseFormatter
+from soothe_cli.shared.tool_formatters.execution import ExecutionFormatter
+from soothe_cli.shared.tool_formatters.fallback import FallbackFormatter
+from soothe_cli.shared.tool_formatters.file_ops import FileOpsFormatter
+from soothe_cli.shared.tool_formatters.goal_formatter import GoalFormatter
+from soothe_cli.shared.tool_formatters.media import MediaFormatter
+from soothe_cli.shared.tool_formatters.structured import StructuredFormatter
+from soothe_cli.shared.tool_formatters.web import WebFormatter
+
+__all__ = [
+    "BaseFormatter",
+    "ExecutionFormatter",
+    "FallbackFormatter",
+    "FileOpsFormatter",
+    "GoalFormatter",
+    "MediaFormatter",
+    "StructuredFormatter",
+    "WebFormatter",
+]

soothe_cli/shared/tool_formatters/base.py

@@ -0,0 +1,109 @@
+"""Base formatter interface for tool output summarization."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from soothe_cli.shared.tool_output_formatter import ToolBrief
+
+# Byte size thresholds
+_KB = 1024
+_MB = _KB * 1024
+_GB = _MB * 1024
+
+
+class BaseFormatter(ABC):
+    """Abstract base class for tool-specific formatters.
+
+    Each formatter implements semantic summarization for a category of tools
+    (file operations, execution, media, goals, etc.).
+    """
+
+    @abstractmethod
+    def format(self, tool_name: str, result: Any) -> ToolBrief:
+        """Format tool result into semantic summary.
+
+        Args:
+            tool_name: Name of the tool (e.g., "read_file", "run_command").
+            result: Tool result (can be str, dict, ToolOutput, or other).
+
+        Returns:
+            ToolBrief with semantic summary.
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def _format_size(size_bytes: int) -> str:
+        """Format byte size as human-readable string.
+
+        Args:
+            size_bytes: Size in bytes.
+
+        Returns:
+            Human-readable size string (e.g., "2.3 KB", "1.5 MB").
+
+        Example:
+            >>> BaseFormatter._format_size(1024)
+            '1.0 KB'
+            >>> BaseFormatter._format_size(1536)
+            '1.5 KB'
+            >>> BaseFormatter._format_size(1048576)
+            '1.0 MB'
+        """
+        if size_bytes < _KB:
+            return f"{size_bytes} B"
+        if size_bytes < _MB:
+            size_kb = size_bytes / _KB
+            return f"{size_kb:.1f} KB"
+        if size_bytes < _GB:
+            size_mb = size_bytes / _MB
+            return f"{size_mb:.1f} MB"
+        size_gb = size_bytes / _GB
+        return f"{size_gb:.1f} GB"
+
+    @staticmethod
+    def _count_lines(text: str) -> int:
+        r"""Count number of lines in text.
+
+        Args:
+            text: Text to count lines in.
+
+        Returns:
+            Number of lines (minimum 1 for non-empty text, 0 for empty text).
+
+        Example:
+            >>> BaseFormatter._count_lines("Hello\nWorld\n")
+            2
+            >>> BaseFormatter._count_lines("")
+            0
+            >>> BaseFormatter._count_lines("Single line")
+            1
+        """
+        if not text or not text.strip():
+            return 0
+        return text.count("\n") + 1 if text.strip() else 0
+
+    @staticmethod
+    def _truncate_text(text: str, max_length: int = 80) -> str:
+        """Truncate text to maximum length with ellipsis.
+
+        Args:
+            text: Text to truncate.
+            max_length: Maximum length (default 80).
+
+        Returns:
+            Truncated text with "..." if longer than max_length.
+
+        Example:
+            >>> BaseFormatter._truncate_text("Short text", max_length=10)
+            'Short text'
+            >>> BaseFormatter._truncate_text("Very long text that needs truncation", max_length=20)
+            'Very long text tha...'
+        """
+        if len(text) <= max_length:
+            return text
+        return text[: max_length - 3] + "..."

soothe_cli/shared/tool_formatters/execution.py

@@ -0,0 +1,297 @@
+"""Formatter for execution tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from soothe_cli.shared.tool_formatters.base import BaseFormatter
+from soothe_cli.shared.tool_output_formatter import ToolBrief
+
+
+class ExecutionFormatter(BaseFormatter):
+    """Formatter for execution tools.
+
+    Handles: run_command, run_python, run_background, kill_process
+
+    Provides semantic summaries with success/failure status, PIDs, and error messages.
+    """
+
+    def format(self, tool_name: str, result: Any) -> ToolBrief:
+        """Format execution tool result.
+
+        Args:
+            tool_name: Name of the execution tool.
+            result: Tool result (string or dict depending on tool).
+
+        Returns:
+            ToolBrief with execution summary.
+
+        Raises:
+            ValueError: If tool_name is not a recognized execution tool.
+
+        Example:
+            >>> formatter = ExecutionFormatter()
+            >>> brief = formatter.format("run_command", "output text")
+            >>> brief.to_display()
+            '✓ Done'
+        """
+        # Normalize tool name
+        normalized = tool_name.lower().replace("-", "_").replace(" ", "_")
+
+        # Route to specific formatter
+        if normalized == "run_command":
+            return self._format_run_command(result)
+        if normalized == "run_python":
+            return self._format_run_python(result)
+        if normalized == "run_background":
+            return self._format_run_background(result)
+        if normalized == "kill_process":
+            return self._format_kill_process(result)
+        msg = f"Unknown execution tool: {tool_name}"
+        raise ValueError(msg)
+
+    def _format_run_command(self, result: str) -> ToolBrief:
+        """Format run_command result.
+
+        Shows "Done" for success or "Failed: {reason}" for errors.
+
+        Args:
+            result: Command output or error string.
+
+        Returns:
+            ToolBrief with execution status.
+
+        Example:
+            >>> brief = formatter._format_run_command("command output")
+            >>> brief.summary
+            'Done'
+            >>> brief = formatter._format_run_command("Error: command not found")
+            >>> brief.summary
+            'Failed'
+            >>> brief.detail
+            'command not found'
+        """
+        # Check for error indicators
+        if result.startswith("Error:"):
+            error_msg = result[6:].strip()  # Remove "Error:" prefix
+            return ToolBrief(
+                icon="✗",
+                summary="Failed",
+                detail=self._truncate_text(error_msg, 80),
+                metrics={"error": True},
+            )
+
+        # Check for other error patterns
+        error_indicators = ["failed:", "exception:", "traceback", "command not found"]
+        result_lower = result.lower()
+        if any(indicator in result_lower for indicator in error_indicators):
+            # Extract first line as error message
+            first_line = result.partition("\n")[0].strip()
+            return ToolBrief(
+                icon="✗",
+                summary="Failed",
+                detail=self._truncate_text(first_line, 80),
+                metrics={"error": True},
+            )
+
+        # Success
+        output_size = len(result)
+        detail = None
+
+        # Show output size if there's substantial output
+        if output_size > 0:
+            output_chars = f"{output_size} chars"
+            detail = f"{output_chars} output"
+        else:
+            detail = "no output"
+
+        return ToolBrief(
+            icon="✓",
+            summary="Done",
+            detail=detail,
+            metrics={"output_size": output_size},
+        )
+
+    def _format_run_python(self, result: dict[str, Any]) -> ToolBrief:
+        """Format run_python result.
+
+        Shows execution status with return value type.
+
+        Args:
+            result: Dict with 'success', 'output', 'result', 'error' fields.
+
+        Returns:
+            ToolBrief with execution status.
+
+        Example:
+            >>> brief = formatter._format_run_python({"success": True, "result": 42})
+            >>> brief.summary
+            'Executed'
+            >>> brief.detail
+            'returned: int'
+        """
+        # Handle dict result
+        if isinstance(result, dict):
+            success = result.get("success", True)
+            error = result.get("error")
+            return_value = result.get("result")
+
+            if not success or error:
+                error_msg = str(error) if error else "Execution failed"
+                return ToolBrief(
+                    icon="✗",
+                    summary="Execution failed",
+                    detail=self._truncate_text(error_msg, 80),
+                    metrics={"error": True},
+                )
+
+            # Success
+            detail = None
+            if return_value is not None:
+                return_type = type(return_value).__name__
+                detail = f"returned: {return_type}"
+            else:
+                output = result.get("output", "")
+                detail = f"{len(output)} chars output" if output else "no output"
+
+            return ToolBrief(
+                icon="✓",
+                summary="Executed",
+                detail=detail,
+                metrics={"has_return": return_value is not None},
+            )
+
+        # Handle string result (fallback)
+        if isinstance(result, str):
+            if "error" in result.lower() or "failed" in result.lower():
+                return ToolBrief(
+                    icon="✗",
+                    summary="Execution failed",
+                    detail=self._truncate_text(result, 80),
+                    metrics={"error": True},
+                )
+
+            return ToolBrief(
+                icon="✓",
+                summary="Executed",
+                detail=f"{len(result)} chars output",
+                metrics={},
+            )
+
+        # Unknown type
+        return ToolBrief(
+            icon="✓",
+            summary="Executed",
+            detail=None,
+            metrics={},
+        )
+
+    def _format_run_background(self, result: dict[str, Any]) -> ToolBrief:
+        """Format run_background result.
+
+        Shows PID of started background process.
+
+        Args:
+            result: Dict with 'pid', 'status', 'message' fields.
+
+        Returns:
+            ToolBrief with PID.
+
+        Example:
+            >>> brief = formatter._format_run_background({"pid": 12345, "status": "running"})
+            >>> brief.summary
+            'Started PID 12345'
+        """
+        # Handle dict result
+        if isinstance(result, dict):
+            pid = result.get("pid")
+            status = result.get("status")
+            message = result.get("message")
+
+            if status == "error" or not pid:
+                error_msg = message or "Failed to start background process"
+                return ToolBrief(
+                    icon="✗",
+                    summary="Start failed",
+                    detail=self._truncate_text(error_msg, 80),
+                    metrics={"error": True},
+                )
+
+            # Success
+            return ToolBrief(
+                icon="✓",
+                summary=f"Started PID {pid}",
+                detail=None,
+                metrics={"pid": pid, "status": status},
+            )
+
+        # Handle string result (fallback)
+        if isinstance(result, str):
+            if "error" in result.lower() or "failed" in result.lower():
+                return ToolBrief(
+                    icon="✗",
+                    summary="Start failed",
+                    detail=self._truncate_text(result, 80),
+                    metrics={"error": True},
+                )
+
+            return ToolBrief(
+                icon="✓",
+                summary="Started",
+                detail=self._truncate_text(result, 80),
+                metrics={},
+            )
+
+        # Unknown type
+        return ToolBrief(
+            icon="✓",
+            summary="Started",
+            detail=None,
+            metrics={},
+        )
+
+    def _format_kill_process(self, result: str) -> ToolBrief:
+        """Format kill_process result.
+
+        Shows termination status with PID.
+
+        Args:
+            result: Success message or error string.
+
+        Returns:
+            ToolBrief with termination status.
+
+        Example:
+            >>> brief = formatter._format_kill_process("Process 12345 terminated")
+            >>> brief.summary
+            'Terminated PID 12345'
+        """
+        # Check for error
+        if "error" in result.lower() or "failed" in result.lower() or "not found" in result.lower():
+            return ToolBrief(
+                icon="✗",
+                summary="Termination failed",
+                detail=self._truncate_text(result, 80),
+                metrics={"error": True},
+            )
+
+        # Try to extract PID from result
+        import re
+
+        pid_match = re.search(r"PID\s+(\d+)", result)
+        if pid_match:
+            pid = pid_match.group(1)
+            return ToolBrief(
+                icon="✓",
+                summary=f"Terminated PID {pid}",
+                detail=None,
+                metrics={"pid": int(pid)},
+            )
+
+        # Generic success
+        return ToolBrief(
+            icon="✓",
+            summary="Terminated",
+            detail=None,
+            metrics={},
+        )