kimi-cli 0.44__py3-none-any.whl → 0.78__py3-none-any.whl

kimi_cli/utils/rich/markdown_sample.md

@@ -0,0 +1,108 @@
+# Markdown Sample Document
+
+This is a comprehensive sample document showcasing various Markdown elements.
+
+## Level 2 Heading
+
+### Level 3 Heading
+
+Here's some regular text with **bold text**, *italic text*, and `inline code`.
+
+## Lists
+
+### Unordered List
+
+- First item
+- Second item
+  - Nested item 1
+  - Nested item 2
+- Third item
+
+### Ordered List
+
+1. First step
+2. Second step
+   1. Sub-step A
+   2. Sub-step B
+3. Third step
+
+### Mixed List
+
+1. First item
+   - Sub-item with bullet
+   - Another sub-item
+2. Second item
+   1. Numbered sub-item
+   2. Another numbered sub-item
+
+## Links and References
+
+Here's a [link to GitHub](https://github.com) and another [relative link](../README.md).
+
+## Code Blocks
+
+```python
+def hello_world():
+    """A simple function to demonstrate code blocks."""
+    print("Hello, World!")
+    return 42
+
+# Call the function
+result = hello_world()
+```
+
+```bash
+# Bash example
+echo "This is a bash script"
+ls -la /tmp
+```
+
+## Blockquotes
+
+> This is a blockquote.
+> It can span multiple lines.
+>
+> > And it can be nested too!
+
+## Tables
+
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Left     | Center   | Right    |
+| Foo      | Bar      | Baz      |
+
+## Horizontal Rules
+
+---
+
+Here's some text after a horizontal rule.
+
+---
+
+## Inline Formatting
+
+You can combine **bold and *italic*** text, or use `code` within paragraphs.
+
+**Important**: Always test your `code` snippets before deployment.
+
+## Advanced Features
+
+### Task Lists
+
+- [x] Completed task
+- [ ] Pending task
+- [ ] Another pending task
+
+### Definition Lists
+
+Term 1
+: Definition of term 1
+
+Term 2
+: Definition of term 2
+: Another definition for term 2
+
+---
+
+*This document demonstrates comprehensive Markdown formatting capabilities.*

kimi_cli/utils/rich/markdown_sample_short.md

@@ -0,0 +1,2 @@
+- First
+- Second

kimi_cli/utils/signals.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import contextlib
 import signal

kimi_cli/utils/slashcmd.py

@@ -0,0 +1,124 @@
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import overload
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SlashCommand[F: Callable[..., None | Awaitable[None]]]:
+    name: str
+    description: str
+    func: F
+    aliases: list[str]
+
+    def slash_name(self):
+        """/name (aliases)"""
+        if self.aliases:
+            return f"/{self.name} ({', '.join(self.aliases)})"
+        return f"/{self.name}"
+
+
+class SlashCommandRegistry[F: Callable[..., None | Awaitable[None]]]:
+    """Registry for slash commands."""
+
+    def __init__(self) -> None:
+        self._commands: dict[str, SlashCommand[F]] = {}
+        """Primary name -> SlashCommand"""
+        self._command_aliases: dict[str, SlashCommand[F]] = {}
+        """Primary name or alias -> SlashCommand"""
+
+    @overload
+    def command(self, func: F, /) -> F: ...
+
+    @overload
+    def command(
+        self,
+        *,
+        name: str | None = None,
+        aliases: Sequence[str] | None = None,
+    ) -> Callable[[F], F]: ...
+
+    def command(
+        self,
+        func: F | None = None,
+        *,
+        name: str | None = None,
+        aliases: Sequence[str] | None = None,
+    ) -> F | Callable[[F], F]:
+        """
+        Decorator to register a slash command with optional custom name and aliases.
+
+        Usage examples:
+          @registry.command
+          def help(app: App, args: str): ...
+
+          @registry.command(name="run")
+          def start(app: App, args: str): ...
+
+          @registry.command(aliases=["h", "?", "assist"])
+          def help(app: App, args: str): ...
+        """
+
+        def _register(f: F) -> F:
+            primary = name or f.__name__
+            alias_list = list(aliases) if aliases else []
+
+            # Create the primary command with aliases
+            cmd = SlashCommand[F](
+                name=primary,
+                description=(f.__doc__ or "").strip(),
+                func=f,
+                aliases=alias_list,
+            )
+
+            # Register primary command
+            self._commands[primary] = cmd
+            self._command_aliases[primary] = cmd
+
+            # Register aliases pointing to the same command
+            for alias in alias_list:
+                self._command_aliases[alias] = cmd
+
+            return f
+
+        if func is not None:
+            return _register(func)
+        return _register
+
+    def find_command(self, name: str) -> SlashCommand[F] | None:
+        return self._command_aliases.get(name)
+
+    def list_commands(self) -> list[SlashCommand[F]]:
+        """Get all unique primary slash commands (without duplicating aliases)."""
+        return list(self._commands.values())
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SlashCommandCall:
+    name: str
+    args: str
+    raw_input: str
+
+
+def parse_slash_command_call(user_input: str) -> SlashCommandCall | None:
+    """
+    Parse a slash command call from user input.
+
+    Returns:
+        SlashCommandCall if a slash command is found, else None. The `args` field contains
+        the raw argument string after the command name.
+    """
+    user_input = user_input.strip()
+    if not user_input or not user_input.startswith("/"):
+        return None
+
+    name_match = re.match(r"^\/([a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)*)", user_input)
+
+    if not name_match:
+        return None
+
+    command_name = name_match.group(1)
+    if len(user_input) > name_match.end() and not user_input[name_match.end()].isspace():
+        return None
+    raw_args = user_input[name_match.end() :].lstrip()
+    return SlashCommandCall(name=command_name, args=raw_args, raw_input=user_input)

kimi_cli/utils/string.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import random
 import re
 import string

kimi_cli/utils/term.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import sys
+import time
+
+
+def ensure_new_line() -> None:
+    """Ensure the next prompt starts at column 0 regardless of prior command output."""
+
+    if not sys.stdout.isatty() or not sys.stdin.isatty():
+        return
+
+    needs_break = True
+    if sys.platform == "win32":
+        column = _cursor_column_windows()
+        needs_break = column not in (None, 0)
+    else:
+        column = _cursor_column_unix()
+        needs_break = column not in (None, 1)
+
+    if needs_break:
+        _write_newline()
+
+
+def ensure_tty_sane() -> None:
+    """Restore basic tty settings so Ctrl-C works after raw-mode operations."""
+    if sys.platform == "win32" or not sys.stdin.isatty():
+        return
+
+    try:
+        import termios
+    except Exception:
+        return
+
+    try:
+        fd = sys.stdin.fileno()
+        attrs = termios.tcgetattr(fd)
+    except Exception:
+        return
+
+    desired = termios.ISIG | termios.IEXTEN | termios.ICANON | termios.ECHO
+    if (attrs[3] & desired) == desired:
+        return
+
+    attrs[3] |= desired
+    with contextlib.suppress(OSError):
+        termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
+
+
+def _cursor_position_unix() -> tuple[int, int] | None:
+    """Get cursor position (row, column) on Unix. Both are 1-indexed."""
+    assert sys.platform != "win32"
+
+    import select
+    import termios
+    import tty
+
+    _CURSOR_QUERY = "\x1b[6n"
+    _CURSOR_POSITION_RE = re.compile(r"\x1b\[(\d+);(\d+)R")
+
+    fd = sys.stdin.fileno()
+    oldterm = termios.tcgetattr(fd)
+
+    try:
+        tty.setcbreak(fd)
+        sys.stdout.write(_CURSOR_QUERY)
+        sys.stdout.flush()
+
+        response = ""
+        deadline = time.monotonic() + 0.2
+        while time.monotonic() < deadline:
+            timeout = max(0.01, deadline - time.monotonic())
+            ready, _, _ = select.select([sys.stdin], [], [], timeout)
+            if not ready:
+                continue
+            try:
+                chunk = os.read(fd, 32)
+            except OSError:
+                break
+            if not chunk:
+                break
+            response += chunk.decode(encoding="utf-8", errors="ignore")
+            match = _CURSOR_POSITION_RE.search(response)
+            if match:
+                return int(match.group(1)), int(match.group(2))
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, oldterm)
+
+    return None
+
+
+def _cursor_column_unix() -> int | None:
+    pos = _cursor_position_unix()
+    return pos[1] if pos else None
+
+
+def _cursor_position_windows() -> tuple[int, int] | None:
+    """Get cursor position (row, column) on Windows. Both are 1-indexed."""
+    assert sys.platform == "win32"
+
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.windll.kernel32
+    _STD_OUTPUT_HANDLE = -11  # Windows API constant for standard output handle
+    handle = kernel32.GetStdHandle(_STD_OUTPUT_HANDLE)
+    invalid_handle_value = ctypes.c_void_p(-1).value
+    if handle in (0, invalid_handle_value):
+        return None
+
+    class COORD(ctypes.Structure):
+        _fields_ = [("X", wintypes.SHORT), ("Y", wintypes.SHORT)]
+
+    class SMALL_RECT(ctypes.Structure):
+        _fields_ = [
+            ("Left", wintypes.SHORT),
+            ("Top", wintypes.SHORT),
+            ("Right", wintypes.SHORT),
+            ("Bottom", wintypes.SHORT),
+        ]
+
+    class CONSOLE_SCREEN_BUFFER_INFO(ctypes.Structure):
+        _fields_ = [
+            ("dwSize", COORD),
+            ("dwCursorPosition", COORD),
+            ("wAttributes", wintypes.WORD),
+            ("srWindow", SMALL_RECT),
+            ("dwMaximumWindowSize", COORD),
+        ]
+
+    csbi = CONSOLE_SCREEN_BUFFER_INFO()
+    if not kernel32.GetConsoleScreenBufferInfo(handle, ctypes.byref(csbi)):
+        return None
+
+    # Windows returns 0-indexed, convert to 1-indexed for consistency
+    return int(csbi.dwCursorPosition.Y) + 1, int(csbi.dwCursorPosition.X) + 1
+
+
+def _cursor_column_windows() -> int | None:
+    pos = _cursor_position_windows()
+    return pos[1] if pos else None
+
+
+def _write_newline() -> None:
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def get_cursor_row() -> int | None:
+    """Get the current cursor row (1-indexed)."""
+    if not sys.stdout.isatty() or not sys.stdin.isatty():
+        return None
+
+    if sys.platform == "win32":
+        pos = _cursor_position_windows()
+    else:
+        pos = _cursor_position_unix()
+
+    return pos[0] if pos else None
+
+
+if __name__ == "__main__":
+    print("test", end="", flush=True)
+    ensure_new_line()
+    print("next line")

kimi_cli/utils/typing.py

@@ -0,0 +1,20 @@
+from types import UnionType
+from typing import Any, TypeAliasType, Union, get_args, get_origin
+
+
+def flatten_union(tp: Any) -> tuple[Any, ...]:
+    """
+    If `tp` is a `UnionType`, return its flattened arguments as a tuple.
+    Otherwise, return a tuple with `tp` as the only element.
+    """
+    if isinstance(tp, TypeAliasType):
+        tp = tp.__value__
+    origin = get_origin(tp)
+    if origin in (UnionType, Union):
+        args = get_args(tp)
+        flattened_args: list[Any] = []
+        for arg in args:
+            flattened_args.extend(flatten_union(arg))
+        return tuple(flattened_args)
+    else:
+        return (tp,)

kimi_cli/wire/__init__.py

@@ -1,54 +1,116 @@
+from __future__ import annotations
+
 import asyncio
+import copy
+import json
+import time
+from pathlib import Path
 
-from kosong.base.message import ContentPart, ToolCallPart
+import aiofiles
+from kosong.message import MergeableMixin
 
+from kimi_cli.utils.aioqueue import Queue, QueueShutDown
+from kimi_cli.utils.broadcast import BroadcastQueue
 from kimi_cli.utils.logging import logger
-from kimi_cli.wire.message import WireMessage
+from kimi_cli.wire.serde import WireMessageRecord
+from kimi_cli.wire.types import ContentPart, ToolCallPart, WireMessage, is_wire_message
+
+WireMessageQueue = BroadcastQueue[WireMessage]
 
 
 class Wire:
     """
-    A channel for communication between the soul and the UI during a soul run.
+    A spmc channel for communication between the soul and the UI during a soul run.
     """
 
-    def __init__(self):
-        self._queue = asyncio.Queue[WireMessage]()
-        self._soul_side = WireSoulSide(self._queue)
-        self._ui_side = WireUISide(self._queue)
+    def __init__(self, *, file_backend: Path | None = None):
+        self._raw_queue = WireMessageQueue()
+        self._merged_queue = WireMessageQueue()
+
+        self._soul_side = WireSoulSide(self._raw_queue, self._merged_queue)
+
+        if file_backend is not None:
+            # record all complete Wire messages to the file backend
+            self._recorder = _WireRecorder(file_backend, self._merged_queue.subscribe())
+        else:
+            self._recorder = None
 
     @property
-    def soul_side(self) -> "WireSoulSide":
+    def soul_side(self) -> WireSoulSide:
         return self._soul_side
 
-    @property
-    def ui_side(self) -> "WireUISide":
-        return self._ui_side
+    def ui_side(self, *, merge: bool) -> WireUISide:
+        """
+        Create a UI side of the `Wire`.
+
+        Args:
+            merge: Whether to merge `Wire` messages as much as possible.
+        """
+        if merge:
+            return WireUISide(self._merged_queue.subscribe())
+        else:
+            return WireUISide(self._raw_queue.subscribe())
 
     def shutdown(self) -> None:
+        self.soul_side.flush()
         logger.debug("Shutting down wire")
-        self._queue.shutdown()
+        self._raw_queue.shutdown()
+        self._merged_queue.shutdown()
 
 
 class WireSoulSide:
     """
-    The soul side of a wire.
+    The soul side of a `Wire`.
     """
 
-    def __init__(self, queue: asyncio.Queue[WireMessage]):
-        self._queue = queue
+    def __init__(self, raw_queue: WireMessageQueue, merged_queue: WireMessageQueue):
+        self._raw_queue = raw_queue
+        self._merged_queue = merged_queue
+        self._merge_buffer: MergeableMixin | None = None
 
     def send(self, msg: WireMessage) -> None:
         if not isinstance(msg, ContentPart | ToolCallPart):
             logger.debug("Sending wire message: {msg}", msg=msg)
-        self._queue.put_nowait(msg)
+
+        # send raw message
+        try:
+            self._raw_queue.publish_nowait(msg)
+        except QueueShutDown:
+            logger.info("Failed to send raw wire message, queue is shut down: {msg}", msg=msg)
+
+        # merge and send merged message
+        match msg:
+            case MergeableMixin():
+                if self._merge_buffer is None:
+                    self._merge_buffer = copy.deepcopy(msg)
+                elif self._merge_buffer.merge_in_place(msg):
+                    pass
+                else:
+                    self.flush()
+                    self._merge_buffer = copy.deepcopy(msg)
+            case _:
+                self.flush()
+                self._send_merged(msg)
+
+    def flush(self) -> None:
+        if self._merge_buffer is not None:
+            assert is_wire_message(self._merge_buffer)
+            self._send_merged(self._merge_buffer)
+            self._merge_buffer = None
+
+    def _send_merged(self, msg: WireMessage) -> None:
+        try:
+            self._merged_queue.publish_nowait(msg)
+        except QueueShutDown:
+            logger.info("Failed to send merged wire message, queue is shut down: {msg}", msg=msg)
 
 
 class WireUISide:
     """
-    The UI side of a wire.
+    The UI side of a `Wire`.
     """
 
-    def __init__(self, queue: asyncio.Queue[WireMessage]):
+    def __init__(self, queue: Queue[WireMessage]):
         self._queue = queue
 
     async def receive(self) -> WireMessage:
@@ -57,14 +119,21 @@ class WireUISide:
             logger.debug("Receiving wire message: {msg}", msg=msg)
         return msg
 
-    def receive_nowait(self) -> WireMessage | None:
-        """
-        Try receive a message without waiting. If no message is available, return None.
-        """
-        try:
-            msg = self._queue.get_nowait()
-        except asyncio.QueueEmpty:
-            return None
-        if not isinstance(msg, ContentPart | ToolCallPart):
-            logger.debug("Receiving wire message: {msg}", msg=msg)
-        return msg
+
+class _WireRecorder:
+    def __init__(self, file_backend: Path, queue: Queue[WireMessage]) -> None:
+        self._file_backend = file_backend
+        self._task = asyncio.create_task(self._consume_loop(queue))
+
+    async def _consume_loop(self, queue: Queue[WireMessage]) -> None:
+        while True:
+            try:
+                msg = await queue.get()
+                await self._record(msg)
+            except QueueShutDown:
+                break
+
+    async def _record(self, msg: WireMessage) -> None:
+        record = WireMessageRecord.from_wire_message(msg, timestamp=time.time())
+        async with aiofiles.open(self._file_backend, mode="a", encoding="utf-8") as f:
+            await f.write(json.dumps(record.model_dump(mode="json"), ensure_ascii=False) + "\n")

kimi_cli/wire/serde.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from kosong.utils.typing import JsonType
+from pydantic import BaseModel, ConfigDict
+
+from kimi_cli.wire.types import WireMessage, WireMessageEnvelope
+
+
+def serialize_wire_message(msg: WireMessage) -> dict[str, JsonType]:
+    """
+    Convert a `WireMessage` into a jsonifiable dict.
+    """
+    envelope = WireMessageEnvelope.from_wire_message(msg)
+    return envelope.model_dump(mode="json")
+
+
+def deserialize_wire_message(data: dict[str, JsonType] | Any) -> WireMessage:
+    """
+    Convert a jsonifiable dict into a `WireMessage`.
+
+    Raises:
+        ValueError: If the message type is unknown or the payload is invalid.
+    """
+    envelope = WireMessageEnvelope.model_validate(data)
+    return envelope.to_wire_message()
+
+
+class WireMessageRecord(BaseModel):
+    """
+    The persisted record of a `WireMessage`.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    timestamp: float
+    message: WireMessageEnvelope
+
+    @classmethod
+    def from_wire_message(cls, msg: WireMessage, *, timestamp: float) -> WireMessageRecord:
+        return cls(timestamp=timestamp, message=WireMessageEnvelope.from_wire_message(msg))
+
+    def to_wire_message(self) -> WireMessage:
+        return self.message.to_wire_message()