soothe-cli 0.1.0__py3-none-any.whl

soothe_cli/cli/renderer.py

@@ -0,0 +1,444 @@
+"""CLI renderer implementing RendererProtocol for headless output.
+
+This module provides the CliRenderer class that outputs events to
+stdout (assistant text) and stderr (progress/tool events).
+Uses StreamDisplayPipeline for RFC-0020 compliant progress display.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from soothe_sdk import get_tool_display_name
+from soothe_sdk.verbosity import VerbosityTier
+
+from soothe_cli.cli.stream import DisplayLine, StreamDisplayPipeline
+from soothe_cli.cli.utils import make_tool_block
+from soothe_cli.shared.display_policy import VerbosityLevel, normalize_verbosity
+from soothe_cli.shared.message_processing import format_tool_call_args
+from soothe_cli.shared.presentation_engine import PresentationEngine
+from soothe_cli.shared.suppression_state import SuppressionState
+
+if TYPE_CHECKING:
+    from soothe_sdk import Plan
+
+
+@dataclass
+class CliRendererState:
+    """CLI-specific display state."""
+
+    # Track if stdout needs newline before stderr output
+    needs_stdout_newline: bool = False
+
+    # Track if stderr was just written (to add spacing before next stdout)
+    stderr_just_written: bool = False
+
+    # Multi-step/agentic suppression state (IG-143)
+    suppression: SuppressionState = field(default_factory=SuppressionState)
+
+    # Track current plan for status display
+    current_plan: Plan | None = None
+
+    # Track tool call start times for duration display (RFC-0020)
+    tool_call_start_times: dict[str, float] = field(default_factory=dict)
+
+    # After LLM text on stdout, next stderr icon block gets one leading blank line
+    stderr_blank_before_next_icon_block: bool = False
+
+
+class CliRenderer:
+    """CLI renderer for headless stdout/stderr output.
+
+    Implements RendererProtocol callbacks for CLI mode:
+    - Assistant text -> stdout (streaming)
+    - Tool calls/results -> stderr (flat stream)
+    - Progress events -> stderr via StreamDisplayPipeline
+    - Errors -> stderr
+
+    Spacing: Soothe-originated stderr lines (icons from the pipeline, tools, results,
+    errors) call `_stderr_begin_icon_block()`, which inserts one blank stderr line only
+    after LLM text was written to stdout, so icon blocks separate from answers without
+    extra blank lines inside the LLM stream or between consecutive stderr lines.
+
+    Usage:
+        renderer = CliRenderer(verbosity="normal")
+        processor = EventProcessor(renderer, verbosity="normal")
+    """
+
+    def __init__(
+        self,
+        *,
+        verbosity: VerbosityLevel = "normal",
+        presentation_engine: PresentationEngine | None = None,
+    ) -> None:
+        """Initialize CLI renderer.
+
+        Args:
+            verbosity: Progress visibility level.
+            presentation_engine: Shared presentation engine (optional).
+        """
+        self._verbosity = normalize_verbosity(verbosity)
+        self._state = CliRendererState()
+        self._presentation = presentation_engine or PresentationEngine()
+        self._pipeline = StreamDisplayPipeline(
+            verbosity=verbosity,
+            presentation_engine=self._presentation,
+        )
+
+    def _rebind_presentation(self, engine: PresentationEngine) -> None:
+        """Attach a shared presentation engine (used by EventProcessor wiring)."""
+        self._presentation = engine
+        self._pipeline = StreamDisplayPipeline(
+            verbosity=self._verbosity,
+            presentation_engine=engine,
+        )
+
+    @property
+    def full_response(self) -> list[str]:
+        """Get accumulated response text."""
+        return self._state.suppression.full_response
+
+    @property
+    def multi_step_active(self) -> bool:
+        """Whether multi-step plan is active."""
+        return self._state.suppression.multi_step_active
+
+    @property
+    def presentation_engine(self) -> PresentationEngine:
+        """Shared presentation policy used with StreamDisplayPipeline and EventProcessor."""
+        return self._presentation
+
+    def write_lines(self, lines: list[DisplayLine]) -> None:
+        """Write display lines to stderr.
+
+        Args:
+            lines: List of DisplayLine objects to render.
+        """
+        if not lines:
+            return
+
+        self._stderr_begin_icon_block()
+
+        for line in lines:
+            sys.stderr.write(line.format() + "\n")
+
+        sys.stderr.flush()
+        self._state.stderr_just_written = True
+
+    def _write_stdout_final_report(self, text: str) -> None:
+        """Write aggregated final answer to stdout (multi-step headless mode only)."""
+        stripped = text.strip()
+        if not stripped:
+            return
+
+        self._state.suppression.full_response.append(stripped)
+
+        # Add newline before final report if stderr was just written (goal completion)
+        if self._state.stderr_just_written:
+            sys.stdout.write("\n")
+            self._state.stderr_just_written = False
+
+        sys.stdout.write(stripped)
+        if not stripped.endswith("\n"):
+            sys.stdout.write("\n")
+        sys.stdout.flush()
+        self._state.needs_stdout_newline = True
+        self._state.stderr_blank_before_next_icon_block = True
+        self._presentation.mark_final_answer_locked()
+
+    def on_assistant_text(
+        self,
+        text: str,
+        *,
+        is_main: bool,
+        is_streaming: bool,  # noqa: ARG002
+    ) -> None:
+        """Write assistant text to stdout.
+
+        HARD SUPPRESS during multi-step execution to prevent intermediate
+        LLM response text from flooding output (IG-143).
+
+        Args:
+            text: Text content to display.
+            is_main: True if from main agent.
+            is_streaming: True if partial chunk.
+        """
+        if not is_main:
+            return  # Subagent text not shown in CLI headless mode
+
+        # HARD BLOCK: No text during multi-step execution (IG-143)
+        if self._state.suppression.should_suppress_output():
+            # Accumulate for final report instead
+            self._state.suppression.accumulate_text(text)
+            return
+
+        # Emit only on final iteration (after flags cleared)
+        self._state.suppression.full_response.append(text)
+
+        if self._state.stderr_just_written:
+            self._state.stderr_just_written = False
+
+        # LLM stream: do not inject extra blank lines (spacing before icon stderr
+        # is handled in _stderr_begin_icon_block when progress resumes).
+        sys.stdout.write(text)
+        sys.stdout.flush()
+        self._state.needs_stdout_newline = True
+        self._state.stderr_blank_before_next_icon_block = True
+
+    def on_tool_call(
+        self,
+        name: str,
+        args: dict[str, Any],
+        tool_call_id: str,
+        *,
+        is_main: bool,  # noqa: ARG002
+    ) -> None:
+        """Write tool call to stderr as a flat stream line.
+
+        Args:
+            name: Tool name.
+            args: Parsed arguments (may contain _raw for fallback).
+            tool_call_id: Tool call identifier.
+            is_main: True if from main agent.
+        """
+        if not self._presentation.tier_visible(VerbosityTier.NORMAL, self._verbosity):
+            return
+
+        # HARD SUPPRESS during multi-step execution (IG-143)
+        if self._state.suppression.should_suppress_output():
+            return
+
+        self._stderr_begin_icon_block()
+
+        display_name = get_tool_display_name(name)
+
+        # Pass args directly, including any _raw fallback
+        args_str = format_tool_call_args(name, {"args": args, "_raw": args.get("_raw", "")})
+
+        # Use display helper for consistency with TUI (RFC-0020 Principle 5)
+        tool_block = make_tool_block(display_name, args_str, status="running")
+
+        # Track start time for duration display (RFC-0020)
+        if tool_call_id:
+            self._state.tool_call_start_times[tool_call_id] = time.time()
+
+        sys.stderr.write(f"{tool_block}\n")
+        sys.stderr.flush()
+        # Mark that stderr was just written
+        self._state.stderr_just_written = True
+
+    def on_tool_result(
+        self,
+        name: str,  # noqa: ARG002
+        result: str,
+        tool_call_id: str,
+        *,
+        is_error: bool,
+        is_main: bool,  # noqa: ARG002
+    ) -> None:
+        """Write tool result to stderr as a flat stream line with duration.
+
+        Args:
+            name: Tool name.
+            result: Result content (truncated).
+            tool_call_id: Tool call identifier.
+            is_error: True if result indicates error.
+            is_main: True if from main agent.
+        """
+        if not self._presentation.tier_visible(VerbosityTier.NORMAL, self._verbosity):
+            return
+
+        # HARD SUPPRESS during multi-step execution (IG-143)
+        if self._state.suppression.should_suppress_output():
+            return
+
+        self._stderr_begin_icon_block()
+
+        # Calculate duration (RFC-0020)
+        duration_ms = 0
+        if tool_call_id and tool_call_id in self._state.tool_call_start_times:
+            start_time = self._state.tool_call_start_times.pop(tool_call_id)
+            duration_ms = int((time.time() - start_time) * 1000)
+
+        # Note: extract_tool_brief() may already include ✓/✗ icon
+        result = self._presentation.summarize_tool_result(result)
+        result_stripped = result.lstrip()
+        if result_stripped.startswith(("✓", "✗")):
+            result_line = result
+        else:
+            icon = "✗" if is_error else "✓"
+            result_line = f"{icon} {result}"
+        if duration_ms > 0:
+            result_line += f" ({duration_ms}ms)"
+
+        sys.stderr.write(result_line + "\n")
+        sys.stderr.flush()
+
+    def on_status_change(self, state: str) -> None:
+        """Handle status changes.
+
+        No-op for CLI - status tracked by event loop.
+
+        Args:
+            state: New daemon state.
+        """
+
+    def on_error(self, error: str, *, context: str | None = None) -> None:
+        """Write error to stderr.
+
+        Args:
+            error: Error message.
+            context: Optional error context.
+        """
+        self._stderr_begin_icon_block()
+        prefix = f"[{context}] " if context else ""
+        sys.stderr.write(f"{prefix}ERROR: {error}\n")
+        sys.stderr.flush()
+        # Mark that stderr was just written
+        self._state.stderr_just_written = True
+
+    def on_progress_event(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+        *,
+        namespace: tuple[str, ...],  # noqa: ARG002
+    ) -> None:
+        """Write progress event to stderr using StreamDisplayPipeline.
+
+        Args:
+            event_type: Event type string.
+            data: Event payload.
+            namespace: Subagent namespace.
+        """
+        # Track suppression state from event (IG-143)
+        final_stdout = self._state.suppression.track_from_event(event_type, data)
+
+        payload = dict(data)
+        payload.pop("final_stdout_message", None)
+
+        # Build event dict for pipeline
+        event = {"type": event_type, **payload}
+        lines = self._pipeline.process(event)
+        self.write_lines(lines)
+
+        # Emit final report on loop completion (IG-143)
+        if self._state.suppression.should_emit_final_report(event_type, final_stdout):
+            response = self._state.suppression.get_final_response(final_stdout)
+            self._write_stdout_final_report(response)
+
+    def on_plan_created(self, plan: Plan) -> None:
+        """Write plan creation to stderr.
+
+        Args:
+            plan: Created plan object.
+        """
+        self._state.current_plan = plan
+        self._state.suppression.track_from_plan(len(plan.steps))
+
+        # Use pipeline for consistent formatting
+        event = {
+            "type": "soothe.cognition.plan.creating",
+            "goal": plan.goal,
+            "steps": [{"id": s.id, "description": s.description} for s in plan.steps],
+        }
+        lines = self._pipeline.process(event)
+        self.write_lines(lines)
+
+    def on_plan_step_started(self, step_id: str, description: str) -> None:
+        """Update plan state and show step header.
+
+        Args:
+            step_id: Step identifier.
+            description: Step description.
+        """
+        # Update step status in current plan
+        if self._state.current_plan:
+            for step in self._state.current_plan.steps:
+                if step.id == step_id:
+                    step.status = "in_progress"
+                    break
+
+        # Use pipeline for consistent formatting
+        event = {
+            "type": "soothe.cognition.plan.step.started",
+            "step_id": step_id,
+            "description": description,
+        }
+        lines = self._pipeline.process(event)
+        self.write_lines(lines)
+
+    def on_plan_step_completed(
+        self,
+        step_id: str,
+        success: bool,  # noqa: FBT001
+        duration_ms: int,
+    ) -> None:
+        """Update plan state and show step completion.
+
+        Args:
+            step_id: Step identifier.
+            success: True if step succeeded.
+            duration_ms: Step duration in milliseconds.
+        """
+        # Update step status in current plan
+        if self._state.current_plan:
+            for step in self._state.current_plan.steps:
+                if step.id == step_id:
+                    step.status = "completed" if success else "failed"
+                    break
+
+        # Use pipeline for consistent formatting
+        event = {
+            "type": "soothe.cognition.plan.step.completed",
+            "step_id": step_id,
+            "success": success,
+            "duration_ms": duration_ms,
+        }
+        lines = self._pipeline.process(event)
+        self.write_lines(lines)
+
+    def on_turn_end(self) -> None:
+        """Finalize output on turn end.
+
+        If multi_step_active was suppressing output, flush the accumulated
+        response to stdout now that the plan is complete.
+        """
+        # Capture state BEFORE resetting
+        was_multi_step = self._state.suppression.multi_step_active
+        accumulated_response = self._state.suppression.full_response
+
+        # Reset state for next turn FIRST (before output logic)
+        self._state.needs_stdout_newline = False
+        self._state.suppression.reset_turn()
+
+        # Multi-step mode intentionally suppresses step body output in headless CLI.
+        # For single-step mode, keep existing newline flush behavior.
+        if (not was_multi_step) and accumulated_response:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+    def _stderr_begin_icon_block(self) -> None:
+        """Prepare stderr for Soothe icon lines (progress, tools, tool results).
+
+        Ensures stdout ends with a newline, then inserts one blank stderr line
+        only after LLM content was written to stdout so icon streams stay visually
+        separated without double-spacing consecutive stderr lines.
+        """
+        self._ensure_newline()
+        if self._state.stderr_blank_before_next_icon_block:
+            sys.stderr.write("\n")
+            self._state.stderr_blank_before_next_icon_block = False
+
+    def _ensure_newline(self) -> None:
+        """Ensure stdout has newline before stderr output.
+
+        This prevents stderr output from mixing into stdout lines.
+        """
+        if self._state.needs_stdout_newline:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+            self._state.needs_stdout_newline = False

soothe_cli/cli/stream/__init__.py

@@ -0,0 +1,17 @@
+"""CLI stream display pipeline for progress output.
+
+This package implements RFC-0020 CLI Stream Display Pipeline,
+providing a unified event-to-output pipeline with integrated
+verbosity filtering and context tracking.
+"""
+
+from soothe_cli.cli.stream.context import PipelineContext, ToolCallInfo
+from soothe_cli.cli.stream.display_line import DisplayLine
+from soothe_cli.cli.stream.pipeline import StreamDisplayPipeline
+
+__all__ = [
+    "DisplayLine",
+    "PipelineContext",
+    "StreamDisplayPipeline",
+    "ToolCallInfo",
+]

soothe_cli/cli/stream/context.py

@@ -0,0 +1,138 @@
+"""Pipeline context for tracking CLI display state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToolCallInfo:
+    """Information about an in-progress tool call.
+
+    Attributes:
+        name: Tool name.
+        args_summary: Truncated args summary.
+        start_time: Start timestamp (time.time()).
+    """
+
+    name: str
+    args_summary: str
+    start_time: float
+
+
+@dataclass
+class PipelineContext:
+    """Context tracking for CLI stream display pipeline.
+
+    Tracks goal, step, and tool state to produce contextual output.
+
+    Attributes:
+        current_goal: Current goal description.
+        goal_start_time: Goal start timestamp.
+        steps_total: Total steps in current goal.
+        steps_completed: Completed step count.
+        current_step_id: Active step ID.
+        current_step_description: Active step description.
+        step_start_time: Step start timestamp.
+        pending_tool_calls: Tool calls awaiting results.
+        parallel_mode: Whether multiple tools are running.
+        subagent_name: Active subagent name.
+        subagent_milestones: Accumulated subagent milestones.
+    """
+
+    # Goal state
+    current_goal: str | None = None
+    goal_start_time: float | None = None
+    steps_total: int = 0
+    steps_completed: int = 0
+
+    # Step state
+    current_step_id: str | None = None
+    current_step_description: str | None = None
+    step_start_time: float | None = None
+    step_header_emitted: bool = False  # Track if step header was emitted
+    _active_step_ids: list[str] = field(default_factory=list)  # Track parallel steps in progress
+    step_descriptions: dict[str, str] = field(default_factory=dict)  # Track descriptions by step ID
+
+    # Parallel tool tracking
+    pending_tool_calls: dict[str, ToolCallInfo] = field(default_factory=dict)
+    parallel_mode: bool = False
+    parallel_header_emitted: bool = False  # Track if parallel header was emitted
+
+    # Subagent tracking
+    subagent_name: str | None = None
+    subagent_milestones: list[str] = field(default_factory=list)
+
+    def reset_goal(self) -> None:
+        """Reset goal-related state."""
+        self.current_goal = None
+        self.goal_start_time = None
+        self.steps_total = 0
+        self.steps_completed = 0
+        self._active_step_ids.clear()
+        self.step_descriptions.clear()
+        self.reset_step()
+
+    def reset_step(self) -> None:
+        """Reset step-related state."""
+        self.current_step_id = None
+        self.current_step_description = None
+        self.step_start_time = None
+        self.step_header_emitted = False
+        self.pending_tool_calls.clear()
+        self.parallel_mode = False
+        self.parallel_header_emitted = False
+        self.subagent_name = None
+        self.subagent_milestones.clear()
+        # Don't clear _active_step_ids here - it's cleared when steps complete
+
+    def complete_step(self, step_id: str) -> None:
+        """Mark a step as completed and update tracking.
+
+        Args:
+            step_id: Step identifier to mark complete.
+        """
+        # Remove from active steps
+        if step_id in self._active_step_ids:
+            self._active_step_ids.remove(step_id)
+        # Increment completed count
+        self.steps_completed += 1
+
+    def start_tool_call(
+        self, tool_call_id: str, name: str, args_summary: str, start_time: float
+    ) -> None:
+        """Register a tool call as started.
+
+        Args:
+            tool_call_id: Tool call identifier.
+            name: Tool name.
+            args_summary: Truncated args.
+            start_time: Start timestamp.
+        """
+        self.pending_tool_calls[tool_call_id] = ToolCallInfo(
+            name=name,
+            args_summary=args_summary,
+            start_time=start_time,
+        )
+        # Enable parallel mode if multiple tools running
+        if len(self.pending_tool_calls) > 1:
+            self.parallel_mode = True
+
+    def complete_tool_call(self, tool_call_id: str) -> ToolCallInfo | None:
+        """Mark a tool call as completed.
+
+        Args:
+            tool_call_id: Tool call identifier.
+
+        Returns:
+            ToolCallInfo if found, None otherwise.
+        """
+        info = self.pending_tool_calls.pop(tool_call_id, None)
+        # Disable parallel mode when all tools complete
+        if not self.pending_tool_calls:
+            self.parallel_mode = False
+            self.parallel_header_emitted = False
+        return info
+
+
+__all__ = ["PipelineContext", "ToolCallInfo"]

soothe_cli/cli/stream/display_line.py

@@ -0,0 +1,83 @@
+"""DisplayLine dataclass for structured CLI output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_MS_PER_SECOND = 1000
+
+
+@dataclass
+class DisplayLine:
+    """Structured output unit for CLI stream display.
+
+    Attributes:
+        level: Semantic level (1=goal, 2=step/tool, 3=result); indent is flat for all.
+        content: Text content to display.
+        icon: Icon prefix ("●", "○", "⚙", "✓", "✗", "→", etc.).
+        indent: Indentation string (headless stream uses no tree indent).
+        status: Optional status suffix ("running" for parallel tools).
+        duration_ms: Optional duration in milliseconds.
+        source_prefix: Optional source identifier for debug mode (e.g., "[main]", "[subagent:research]").
+        newline_before: Add newline separator before this line for improved readability.
+    """
+
+    level: int
+    content: str
+    icon: str
+    indent: str
+    status: str | None = None
+    duration_ms: int | None = None
+    source_prefix: str | None = None
+    newline_before: bool = False
+
+    def format(self) -> str:
+        """Format the display line as a string.
+
+        Returns:
+            Formatted line ready for output.
+        """
+        parts = []
+
+        # Add newline separator before if requested (for improved readability)
+        if self.newline_before:
+            parts.append("\n")
+
+        # Add source prefix first if present (debug mode)
+        if self.source_prefix:
+            parts.append(self.source_prefix)
+            parts.append(" ")
+
+        # Handle empty icon (connector already in indent)
+        if self.icon:
+            parts.extend([self.indent, self.icon, " ", self.content])
+        else:
+            parts.extend([self.indent, self.content])
+
+        if self.status:
+            parts.append(f" [{self.status}]")
+
+        if self.duration_ms is not None:
+            if self.duration_ms >= _MS_PER_SECOND:
+                parts.append(f" ({self.duration_ms / _MS_PER_SECOND:.1f}s)")
+            else:
+                parts.append(f" ({self.duration_ms}ms)")
+
+        return "".join(parts)
+
+
+def indent_for_level(_level: int) -> str:
+    """Get indentation string for a display level.
+
+    Headless CLI uses a flat information stream (no tree connectors).
+
+    Args:
+        _level: Display level (1, 2, or 3); retained for API compatibility.
+
+    Returns:
+        Indentation string (always empty for stream layout).
+    """
+    return ""
+
+
+__all__ = ["DisplayLine", "indent_for_level"]