klaude-code 1.2.6__py3-none-any.whl

klaude_code/trace/__init__.py

@@ -0,0 +1,3 @@
+from .log import DebugType, is_debug_enabled, log, log_debug, logger, set_debug_logging
+
+__all__ = ["log", "log_debug", "logger", "set_debug_logging", "DebugType", "is_debug_enabled"]

klaude_code/trace/log.py

@@ -0,0 +1,168 @@
+import logging
+from enum import Enum
+from logging.handlers import RotatingFileHandler
+from typing import Iterable
+
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.text import Text
+
+from klaude_code import const
+
+# Module-level logger
+logger = logging.getLogger("klaude_code")
+logger.setLevel(logging.DEBUG)
+
+# Console for direct output (user-facing messages)
+log_console = Console()
+
+
+class DebugType(str, Enum):
+    """Debug message categories for filtering."""
+
+    GENERAL = "general"
+    LLM_CONFIG = "llm_config"
+    LLM_PAYLOAD = "llm_payload"
+    LLM_STREAM = "llm_stream"
+    UI_EVENT = "ui_event"
+    RESPONSE = "response"
+    EXECUTION = "execution"
+    TERMINAL = "terminal"
+
+
+class DebugTypeFilter(logging.Filter):
+    """Filter log records based on DebugType."""
+
+    def __init__(self, allowed_types: set[DebugType] | None = None):
+        super().__init__()
+        self.allowed_types = allowed_types
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self.allowed_types is None:
+            return True
+        debug_type = getattr(record, "debug_type", DebugType.GENERAL)
+        return debug_type in self.allowed_types
+
+
+# Handler references for reconfiguration
+_file_handler: RotatingFileHandler | None = None
+_console_handler: RichHandler | None = None
+_debug_filter: DebugTypeFilter | None = None
+_debug_enabled = False
+
+
+def set_debug_logging(
+    enabled: bool,
+    *,
+    write_to_file: bool | None = None,
+    log_file: str | None = None,
+    filters: set[DebugType] | None = None,
+) -> None:
+    """Configure global debug logging behavior.
+
+    Args:
+        enabled: Enable or disable debug logging
+        write_to_file: If True, write to file; if False, output to console
+        log_file: Path to the log file (default: debug.log)
+        filters: Set of DebugType to include; None means all types
+    """
+    global _file_handler, _console_handler, _debug_filter, _debug_enabled
+
+    _debug_enabled = enabled
+
+    # Remove existing handlers
+    if _file_handler is not None:
+        logger.removeHandler(_file_handler)
+        _file_handler.close()
+        _file_handler = None
+    if _console_handler is not None:
+        logger.removeHandler(_console_handler)
+        _console_handler = None
+
+    if not enabled:
+        return
+
+    # Create filter
+    _debug_filter = DebugTypeFilter(filters)
+
+    # Determine output mode
+    use_file = write_to_file if write_to_file is not None else True
+    file_path = log_file if log_file is not None else const.DEFAULT_DEBUG_LOG_FILE
+
+    if use_file:
+        _file_handler = RotatingFileHandler(
+            file_path,
+            maxBytes=const.LOG_MAX_BYTES,
+            backupCount=const.LOG_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+        _file_handler.setLevel(logging.DEBUG)
+        _file_handler.setFormatter(logging.Formatter("[%(asctime)s] %(debug_type_label)-12s %(message)s"))
+        _file_handler.addFilter(_debug_filter)
+        logger.addHandler(_file_handler)
+    else:
+        # Console handler with Rich formatting
+        _console_handler = RichHandler(
+            console=log_console,
+            show_time=False,
+            show_path=False,
+            rich_tracebacks=True,
+        )
+        _console_handler.setLevel(logging.DEBUG)
+        _console_handler.addFilter(_debug_filter)
+        logger.addHandler(_console_handler)
+
+
+def log(*objects: str | tuple[str, str], style: str = "") -> None:
+    """Output user-facing messages to console.
+
+    Args:
+        objects: Strings or (text, style) tuples to print
+        style: Default style for all objects
+    """
+    log_console.print(
+        *((Text(obj[0], style=obj[1]) if isinstance(obj, tuple) else Text(obj)) for obj in objects),
+        style=style,
+    )
+
+
+def log_debug(
+    *objects: str | tuple[str, str],
+    style: str | None = None,
+    debug_type: DebugType = DebugType.GENERAL,
+) -> None:
+    """Log debug messages with category support.
+
+    Args:
+        objects: Strings or (text, style) tuples to log
+        style: Style hint (used for console output)
+        debug_type: Category of the debug message
+    """
+    if not _debug_enabled:
+        return
+
+    message = _build_message(objects)
+
+    # Create log record with extra fields
+    extra = {
+        "debug_type": debug_type,
+        "debug_type_label": debug_type.value.upper(),
+        "style": style,
+    }
+    logger.debug(message, extra=extra)
+
+
+def _build_message(objects: Iterable[str | tuple[str, str]]) -> str:
+    """Build plain text message from objects."""
+    parts: list[str] = []
+    for obj in objects:
+        if isinstance(obj, tuple):
+            parts.append(obj[0])
+        else:
+            parts.append(obj)
+    return " ".join(parts)
+
+
+def is_debug_enabled() -> bool:
+    """Check if debug logging is currently enabled."""
+    return _debug_enabled

klaude_code/ui/__init__.py

@@ -0,0 +1,91 @@
+"""
+UI Module - Display and Input Abstractions for klaude-code
+
+This module provides the UI layer for klaude-code, including display modes
+and input providers. The UI is designed around three main concepts:
+
+Display Modes:
+- REPLDisplay: Interactive terminal mode with Rich rendering, spinners, and live updates
+- ExecDisplay: Non-interactive exec mode that only outputs task results
+- DebugEventDisplay: Decorator that logs all events for debugging purposes
+
+Input Providers:
+- PromptToolkitInput: Interactive input with prompt-toolkit (completions, keybindings)
+
+Factory Functions:
+- create_default_display(): Creates the appropriate display for interactive mode
+- create_exec_display(): Creates the appropriate display for exec mode
+"""
+
+# --- Abstract Interfaces ---
+from .core.display import DisplayABC
+from .core.input import InputProviderABC
+from .modes.debug.display import DebugEventDisplay
+from .modes.exec.display import ExecDisplay, StreamJsonDisplay
+
+# --- Display Mode Implementations ---
+from .modes.repl.display import REPLDisplay
+
+# --- Input Implementations ---
+from .modes.repl.input_prompt_toolkit import PromptToolkitInput
+from .terminal.notifier import TerminalNotifier
+
+
+def create_default_display(
+    debug: bool = False,
+    theme: str | None = None,
+    notifier: TerminalNotifier | None = None,
+) -> DisplayABC:
+    """
+    Create the default display for interactive REPL mode.
+
+    Args:
+        debug: If True, wrap the display with DebugEventDisplay to log all events.
+        theme: Optional theme name ("light" or "dark") for syntax highlighting.
+        notifier: Optional terminal notifier for desktop notifications.
+
+    Returns:
+        A DisplayABC implementation suitable for interactive use.
+    """
+    repl_display = REPLDisplay(theme=theme, notifier=notifier)
+    if debug:
+        return DebugEventDisplay(repl_display)
+    return repl_display
+
+
+def create_exec_display(debug: bool = False, stream_json: bool = False) -> DisplayABC:
+    """
+    Create a display for exec (non-interactive) mode.
+
+    Args:
+        debug: If True, wrap the display with DebugEventDisplay to log all events.
+        stream_json: If True, stream all events as JSON lines instead of normal output.
+
+    Returns:
+        A DisplayABC implementation that only outputs task results.
+    """
+    if stream_json:
+        return StreamJsonDisplay()
+    exec_display = ExecDisplay()
+    if debug:
+        return DebugEventDisplay(exec_display)
+    return exec_display
+
+
+__all__ = [
+    # Abstract interfaces
+    "DisplayABC",
+    "InputProviderABC",
+    # Display mode implementations
+    "REPLDisplay",
+    "ExecDisplay",
+    "StreamJsonDisplay",
+    "DebugEventDisplay",
+    # Input implementations
+    "PromptToolkitInput",
+    # Factory functions
+    "create_default_display",
+    "create_exec_display",
+    # Supporting types
+    "TerminalNotifier",
+]

klaude_code/ui/core/__init__.py

@@ -0,0 +1 @@
+# Core UI abstractions

klaude_code/ui/core/display.py

@@ -0,0 +1,103 @@
+from abc import ABC, abstractmethod
+from asyncio import Queue
+
+from klaude_code.protocol import events
+from klaude_code.trace import log
+
+
+class DisplayABC(ABC):
+    """
+    Abstract base class for UI display implementations.
+
+    A Display is responsible for rendering events from the executor to the user.
+    Implementations can range from simple text output (ExecDisplay) to rich
+    interactive terminals (REPLDisplay) or debugging wrappers (DebugEventDisplay).
+
+    Lifecycle:
+        1. start() is called once before any events are consumed.
+        2. consume_event() is called for each event from the executor.
+        3. stop() is called once when the display is shutting down (after EndEvent).
+
+    Typical Usage:
+        display = create_default_display()
+        await display.consume_event_loop(event_queue)
+
+        # Or manually:
+        await display.start()
+        try:
+            async for event in events:
+                if isinstance(event, EndEvent):
+                    break
+                await display.consume_event(event)
+        finally:
+            await display.stop()
+
+    Thread Safety:
+        Display implementations should be used from a single async task.
+        The consume_event_loop method handles the standard event loop pattern.
+    """
+
+    @abstractmethod
+    async def consume_event(self, event: events.Event) -> None:
+        """
+        Process a single event from the executor.
+
+        This method is called for each event except EndEvent, which triggers stop().
+        Implementations should handle all relevant event types and render them
+        appropriately for the user.
+
+        Args:
+            event: The event to process. See klaude_code.protocol.events for types.
+        """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """
+        Initialize the display before processing events.
+
+        Called once before any consume_event calls. Use this for any setup
+        that needs to happen before rendering begins (e.g., initializing
+        terminal state, starting background tasks).
+        """
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """
+        Clean up the display after all events have been processed.
+
+        Called once after EndEvent is received. Use this for cleanup such as
+        stopping spinners, restoring terminal state, or flushing output buffers.
+        """
+
+    async def consume_event_loop(self, q: Queue[events.Event]) -> None:
+        """
+        Main event loop that processes events from a queue.
+
+        This is the standard entry point for running a display. It handles:
+        - Calling start() before processing
+        - Consuming events until EndEvent is received
+        - Calling stop() after EndEvent
+        - Error handling and logging for individual events
+
+        Args:
+            q: An asyncio Queue of events to process. The loop exits when
+               an EndEvent is received.
+        """
+        await self.start()
+        while True:
+            event = await q.get()
+            try:
+                if isinstance(event, events.EndEvent):
+                    await self.stop()
+                    break
+                await self.consume_event(event)
+            except Exception as e:
+                import traceback
+
+                log(
+                    f"Error in consume_event_loop, {e.__class__.__name__}, {e}",
+                    style="red",
+                )
+                log(traceback.format_exc(), style="red")
+            finally:
+                q.task_done()

klaude_code/ui/core/input.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+from klaude_code.protocol.model import UserInputPayload
+
+
+class InputProviderABC(ABC):
+    """
+    Abstract base class for user input providers.
+
+    An InputProvider is responsible for collecting user input and yielding it
+    to the application. Implementations handle the specifics of input collection,
+    such as terminal readline, prompt-toolkit sessions, or other input sources.
+
+    Lifecycle:
+        1. start() is called once before any inputs are requested.
+        2. iter_inputs() yields user input strings until the user exits.
+        3. stop() is called once when input collection is complete.
+
+    Typical Usage:
+        input_provider = PromptToolkitInput(status_provider=my_status_fn)
+        await input_provider.start()
+        try:
+            async for user_input in input_provider.iter_inputs():
+                if user_input.text.strip().lower() in {"exit", "quit"}:
+                    break
+                # Process user_input.text and user_input.images...
+        finally:
+            await input_provider.stop()
+
+    Thread Safety:
+        Input providers should be used from a single async task.
+    """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """
+        Initialize the input provider before reading inputs.
+
+        Called once before iter_inputs(). Use this for any setup that needs
+        to happen before input collection begins (e.g., configuring terminal
+        settings, loading history).
+        """
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """
+        Clean up the input provider after input collection is complete.
+
+        Called once after iter_inputs() finishes. Use this for cleanup such
+        as saving history, restoring terminal state, or releasing resources.
+        """
+
+    @abstractmethod
+    async def iter_inputs(self) -> AsyncIterator[UserInputPayload]:
+        """
+        Yield user input payloads asynchronously.
+
+        This is the main method for collecting user input. Each yield returns
+        one complete user input payload containing text and optional images
+        (e.g., after the user presses Enter). The iterator completes when the
+        user signals end of input (e.g., Ctrl+D) or when the application
+        requests shutdown.
+
+        Yields:
+            UserInputPayload with text and optional images.
+        """
+        raise NotImplementedError
+        yield UserInputPayload(text="")  # pyright: ignore[reportUnreachable]

klaude_code/ui/core/stage_manager.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Awaitable, Callable
+
+
+class Stage(Enum):
+    WAITING = "waiting"
+    THINKING = "thinking"
+    ASSISTANT = "assistant"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+
+
+class StageManager:
+    """Manage display stage transitions and invoke lifecycle callbacks."""
+
+    def __init__(
+        self,
+        *,
+        finish_assistant: Callable[[], Awaitable[None]],
+        on_enter_thinking: Callable[[], None],
+    ):
+        self._stage = Stage.WAITING
+        self._finish_assistant = finish_assistant
+        self._on_enter_thinking = on_enter_thinking
+
+    @property
+    def current_stage(self) -> Stage:
+        return self._stage
+
+    async def transition_to(self, new_stage: Stage) -> None:
+        if self._stage == new_stage:
+            return
+        await self._leave_current_stage()
+        self._stage = new_stage
+
+    async def enter_thinking_stage(self) -> None:
+        if self._stage == Stage.THINKING:
+            return
+        await self.transition_to(Stage.THINKING)
+        self._on_enter_thinking()
+
+    async def finish_assistant(self) -> None:
+        if self._stage != Stage.ASSISTANT:
+            await self._finish_assistant()
+            return
+        await self._finish_assistant()
+        self._stage = Stage.WAITING
+
+    async def _leave_current_stage(self) -> None:
+        if self._stage == Stage.ASSISTANT:
+            await self.finish_assistant()
+        elif self._stage != Stage.WAITING:
+            self._stage = Stage.WAITING

klaude_code/ui/modes/__init__.py

@@ -0,0 +1 @@
+# UI mode implementations

klaude_code/ui/modes/debug/__init__.py

@@ -0,0 +1 @@
+# Debug mode

klaude_code/ui/modes/debug/display.py

@@ -0,0 +1,36 @@
+from typing import override
+
+from klaude_code import const
+from klaude_code.protocol import events
+from klaude_code.trace import DebugType, log_debug
+from klaude_code.ui.core.display import DisplayABC
+
+
+class DebugEventDisplay(DisplayABC):
+    def __init__(
+        self,
+        wrapped_display: DisplayABC | None = None,
+        log_file: str = const.DEFAULT_DEBUG_LOG_FILE,
+    ):
+        self.wrapped_display = wrapped_display
+        self.log_file = log_file
+
+    @override
+    async def consume_event(self, event: events.Event) -> None:
+        log_debug(
+            f"[{event.__class__.__name__}]",
+            event.model_dump_json(exclude_none=True),
+            style="magenta",
+            debug_type=DebugType.UI_EVENT,
+        )
+
+        if self.wrapped_display:
+            await self.wrapped_display.consume_event(event)
+
+    async def start(self) -> None:
+        if self.wrapped_display:
+            await self.wrapped_display.start()
+
+    async def stop(self) -> None:
+        if self.wrapped_display:
+            await self.wrapped_display.stop()

klaude_code/ui/modes/exec/__init__.py

@@ -0,0 +1 @@
+# Exec mode

klaude_code/ui/modes/exec/display.py

@@ -0,0 +1,63 @@
+import sys
+from typing import override
+
+from klaude_code.protocol import events
+from klaude_code.ui.core.display import DisplayABC
+from klaude_code.ui.terminal.progress_bar import OSC94States, emit_osc94
+
+
+class ExecDisplay(DisplayABC):
+    """A display implementation for exec mode - only handles TaskFinishEvent."""
+
+    @override
+    async def consume_event(self, event: events.Event) -> None:
+        """Only handle TaskFinishEvent."""
+        match event:
+            case events.TaskStartEvent():
+                emit_osc94(OSC94States.INDETERMINATE)
+            case events.ErrorEvent() as e:
+                emit_osc94(OSC94States.HIDDEN)
+                print(f"Error: {e.error_message}")
+            case events.TaskFinishEvent() as e:
+                emit_osc94(OSC94States.HIDDEN)
+                # Print the task result when task finishes
+                if e.task_result.strip():
+                    print(e.task_result)
+            case _:
+                # Ignore all other events
+                pass
+
+    @override
+    async def start(self) -> None:
+        """Do nothing on start."""
+        pass
+
+    @override
+    async def stop(self) -> None:
+        """Do nothing on stop."""
+        pass
+
+
+class StreamJsonDisplay(DisplayABC):
+    """A display implementation that streams all events as JSON lines."""
+
+    @override
+    async def consume_event(self, event: events.Event) -> None:
+        """Stream each event as a JSON line."""
+        if isinstance(event, events.EndEvent):
+            return
+        event_type = type(event).__name__
+        json_data = event.model_dump_json()
+        # Output format: {"type": "EventName", "data": {...}}
+        print(f'{{"type": "{event_type}", "data": {json_data}}}', flush=True)
+        sys.stdout.flush()
+
+    @override
+    async def start(self) -> None:
+        """Do nothing on start."""
+        pass
+
+    @override
+    async def stop(self) -> None:
+        """Do nothing on stop."""
+        pass

klaude_code/ui/modes/repl/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from klaude_code.protocol import model
+from klaude_code.ui.modes.repl.input_prompt_toolkit import REPLStatusSnapshot
+
+if TYPE_CHECKING:
+    from klaude_code.core.agent import Agent
+
+
+def build_repl_status_snapshot(agent: "Agent | None", update_message: str | None) -> REPLStatusSnapshot:
+    """Build a status snapshot for the REPL bottom toolbar.
+
+    Aggregates model name, context usage, and basic call counts from the
+    provided agent's session history.
+    """
+
+    model_name = ""
+    context_usage_percent: float | None = None
+    llm_calls = 0
+    tool_calls = 0
+
+    if agent is not None:
+        profile = agent.profile
+        if profile is not None:
+            model_name = profile.llm_client.model_name or ""
+        else:
+            model_name = "N/A"
+
+        history = agent.session.conversation_history
+        for item in history:
+            if isinstance(item, model.AssistantMessageItem):
+                llm_calls += 1
+            elif isinstance(item, model.ToolCallItem):
+                tool_calls += 1
+
+        for item in reversed(history):
+            if isinstance(item, model.ResponseMetadataItem):
+                usage = item.usage
+                if usage is not None and hasattr(usage, "context_usage_percent"):
+                    context_usage_percent = usage.context_usage_percent
+                break
+
+    return REPLStatusSnapshot(
+        model_name=model_name,
+        context_usage_percent=context_usage_percent,
+        llm_calls=llm_calls,
+        tool_calls=tool_calls,
+        update_message=update_message,
+    )