tsugite-cli 0.3.3__py3-none-any.whl

tsugite/ui/helpers.py

@@ -0,0 +1,102 @@
+"""Helper functions for creating and managing UI loggers."""
+
+from contextlib import contextmanager
+from typing import Generator
+
+from rich.console import Console
+
+from tsugite.ui.base import CustomUIHandler, CustomUILogger
+from tsugite.ui.plain import PlainUIHandler
+from tsugite.ui_context import clear_ui_context, set_ui_context
+
+
+@contextmanager
+def custom_agent_ui(
+    console: Console,
+    show_code: bool = True,
+    show_observations: bool = True,
+    show_progress: bool = True,
+    show_llm_messages: bool = False,
+    show_execution_results: bool = True,
+    show_execution_logs: bool = True,
+    show_panels: bool = True,
+    show_debug_messages: bool = False,
+) -> Generator[CustomUILogger, None, None]:
+    """Context manager for custom agent UI.
+
+    Args:
+        console: Rich console instance
+        show_code: Whether to display executed code
+        show_observations: Whether to display tool observations
+        show_progress: Whether to show progress spinner
+        show_llm_messages: Whether to show LLM reasoning messages
+        show_execution_results: Whether to show code execution results
+        show_execution_logs: Whether to show execution logs
+        show_panels: Whether to show Rich panels (borders and decorations)
+        show_debug_messages: Whether to show debug messages (requires --verbose)
+
+    Yields:
+        CustomUILogger: Logger instance with ui_handler and console
+    """
+    ui_handler = CustomUIHandler(
+        console,
+        show_code=show_code,
+        show_observations=show_observations,
+        show_llm_messages=show_llm_messages,
+        show_execution_results=show_execution_results,
+        show_execution_logs=show_execution_logs,
+        show_panels=show_panels,
+        show_debug_messages=show_debug_messages,
+    )
+    logger = CustomUILogger(ui_handler, console)
+
+    try:
+        if show_progress:
+            # progress_context() will call set_ui_context() with the progress instance
+            with ui_handler.progress_context():
+                yield logger
+        else:
+            # No progress, so set ui_context here without progress
+            set_ui_context(console=console, progress=None, ui_handler=ui_handler)
+            yield logger
+    finally:
+        clear_ui_context()
+
+
+def create_plain_logger() -> CustomUILogger:
+    """Create a plain text logger for copy-paste friendly output.
+
+    Returns a logger using PlainUIHandler with no colors, panels, or emojis.
+    Ideal for:
+    - Piped output
+    - Copy-paste workflows
+    - Screen readers
+    - Logs and automation
+
+    Returns:
+        CustomUILogger with PlainUIHandler
+    """
+    plain_handler = PlainUIHandler()
+    return CustomUILogger(plain_handler, plain_handler.console)
+
+
+def create_live_template_logger(interactive: bool = True) -> CustomUILogger:
+    """Create logger using Live Template handler with Tree and interactive prompts.
+
+    Returns a logger using LiveTemplateHandler with Rich Live Display.
+    Features:
+    - Live Display with multi-panel layout
+    - Tree visualization of execution steps
+    - Interactive prompts (optional)
+    - Real-time updates without scrolling
+
+    Args:
+        interactive: Enable interactive prompts during execution
+
+    Returns:
+        CustomUILogger with LiveTemplateHandler
+    """
+    from tsugite.ui.live_template import LiveTemplateHandler
+
+    handler = LiveTemplateHandler(interactive=interactive)
+    return CustomUILogger(handler, handler.console)

tsugite/ui/jsonl.py

@@ -0,0 +1,125 @@
+"""JSONL UI handler for subprocess-based subagent communication."""
+
+import json
+from typing import Any, Dict
+
+from tsugite.events import (
+    BaseEvent,
+    CodeExecutionEvent,
+    ErrorEvent,
+    ExecutionResultEvent,
+    FinalAnswerEvent,
+    LLMMessageEvent,
+    ObservationEvent,
+    StepStartEvent,
+    TaskStartEvent,
+    ToolCallEvent,
+)
+
+
+class JSONLUIHandler:
+    """Emit UI events as JSONL to stdout for subprocess communication.
+
+    This handler converts all UI events to line-delimited JSON objects,
+    enabling parent agents to monitor subagent progress in real-time.
+
+    JSONL Protocol Schema:
+    ----------------------
+    Each line is a JSON object with a "type" field and type-specific data.
+
+    Event Type Mappings:
+    - TaskStartEvent      → {"type": "init", "agent": str, "model": str}
+    - StepStartEvent      → {"type": "turn_start", "turn": int}
+    - LLMMessageEvent     → {"type": "thought", "content": str}
+    - CodeExecutionEvent  → {"type": "code", "content": str}
+    - ToolCallEvent       → {"type": "tool_call", "tool": str, "args": dict}
+    - ObservationEvent    → {"type": "tool_result", "tool": str, "success": bool, "output"?: str, "error"?: str}
+    - ExecutionResultEvent→ {"type": "tool_result", "tool": "code_execution", "success": bool, "output"?: str, "error"?: str}
+    - FinalAnswerEvent    → {"type": "final_result", "result": str, "turns": int, "tokens": int, "cost": float}
+    - ErrorEvent          → {"type": "error", "error": str, "step": int}
+
+    Success/Failure Patterns:
+    - Successful tool: {"type": "tool_result", "tool": "read_file", "success": true, "output": "..."}
+    - Failed tool: {"type": "tool_result", "tool": "read_file", "success": false, "error": "..."}
+    - Code execution success: {"type": "tool_result", "tool": "code_execution", "success": true, "output": "logs\\nresult"}
+    - Code execution failure: {"type": "tool_result", "tool": "code_execution", "success": false, "error": "..."}
+    """
+
+    def handle_event(self, event: BaseEvent) -> None:
+        """Convert UI event to JSONL and print to stdout.
+
+        Args:
+            event: The Pydantic event
+        """
+        if isinstance(event, TaskStartEvent):
+            self._emit("init", {"agent": event.task, "model": event.model})
+
+        elif isinstance(event, StepStartEvent):
+            self._emit("turn_start", {"turn": event.step})
+
+        elif isinstance(event, LLMMessageEvent):
+            if event.content.strip():
+                self._emit("thought", {"content": event.content})
+
+        elif isinstance(event, CodeExecutionEvent):
+            if event.code:
+                self._emit("code", {"content": event.code})
+
+        elif isinstance(event, ToolCallEvent):
+            self._emit("tool_call", {"tool": event.tool, "args": event.args})
+
+        elif isinstance(event, ObservationEvent):
+            if event.success:
+                self._emit(
+                    "tool_result", {"tool": event.tool or "unknown", "success": True, "output": event.observation}
+                )
+            else:
+                self._emit(
+                    "tool_result",
+                    {"tool": event.tool or "unknown", "success": False, "error": event.error or event.observation},
+                )
+
+        elif isinstance(event, ExecutionResultEvent):
+            if event.success:
+                # Combine logs and output for backward compatibility
+                output = event.output or ""
+                if event.logs:
+                    logs_str = "\n".join(event.logs)
+                    output = f"{logs_str}\n{output}" if output else logs_str
+                self._emit("tool_result", {"tool": "code_execution", "success": True, "output": output})
+            else:
+                self._emit("tool_result", {"tool": "code_execution", "success": False, "error": event.error or ""})
+
+        elif isinstance(event, FinalAnswerEvent):
+            self._emit(
+                "final_result",
+                {
+                    "result": event.answer,
+                    "turns": event.turns,
+                    "tokens": event.tokens,
+                    "cost": event.cost,
+                },
+            )
+
+        elif isinstance(event, ErrorEvent):
+            self._emit("error", {"error": event.error, "step": event.step})
+
+    def _emit(self, event_type: str, data: Dict[str, Any]) -> None:
+        """Print JSONL event to stdout.
+
+        Args:
+            event_type: The event type string
+            data: Event-specific data dictionary
+        """
+        event = {"type": event_type, **data}
+        print(json.dumps(event), flush=True)
+
+    def update_progress(self, description: str) -> None:
+        """No-op for progress updates in JSONL mode."""
+        pass
+
+    def progress_context(self):
+        """No-op context manager for compatibility."""
+        from contextlib import nullcontext
+
+        return nullcontext()