kimi-cli 0.35__py3-none-any.whl

kimi_cli/prompts/metacmds/compact.md

@@ -0,0 +1,74 @@
+You are tasked with compacting a coding conversation context. This is critical for maintaining an effective working memory for the coding agent.
+
+**Compression Priorities (in order):**
+1. **Current Task State**: What is being worked on RIGHT NOW
+2. **Errors & Solutions**: All encountered errors and their resolutions
+3. **Code Evolution**: Final working versions only (remove intermediate attempts)
+4. **System Context**: Project structure, dependencies, environment setup
+5. **Design Decisions**: Architectural choices and their rationale
+6. **TODO Items**: Unfinished tasks and known issues
+
+**Compression Rules:**
+- MUST KEEP: Error messages, stack traces, working solutions, current task
+- MERGE: Similar discussions into single summary points
+- REMOVE: Redundant explanations, failed attempts (keep lessons learned), verbose comments
+- CONDENSE: Long code blocks → keep signatures + key logic only
+
+**Special Handling:**
+- For code: Keep full version if < 20 lines, otherwise keep signature + key logic
+- For errors: Keep full error message + final solution
+- For discussions: Extract decisions and action items only
+
+**Input Context to Compress:**
+
+${CONTEXT}
+
+**Required Output Structure:**
+
+<current_focus>
+[What we're working on now]
+</current_focus>
+
+<environment>
+- [Key setup/config points]
+- ...more...
+</environment>
+
+<completed_tasks>
+- [Task]: [Brief outcome]
+- ...more...
+</completed_tasks>
+
+<active_issues>
+- [Issue]: [Status/Next steps]
+- ...more...
+</active_issues>
+
+<code_state>
+
+<file>
+[filename]
+
+**Summary:**
+[What this code file does]
+
+**Key elements:**
+- [Important functions/classes]
+- ...more...
+
+**Latest version:**
+[Critical code snippets in this file]
+</file>
+
+<file>
+[filename]
+...Similar as above...
+</file>
+
+...more files...
+</code_state>
+
+<important_context>
+- [Any crucial information not covered above]
+- ...more...
+</important_context>

kimi_cli/prompts/metacmds/init.md

@@ -0,0 +1,21 @@
+You are a software engineering expert with many years of programming experience. Please explore the current project directory to understand the project's architecture and main details.
+
+Task requirements:
+1. Analyze the project structure and identify key configuration files (such as pyproject.toml, package.json, Cargo.toml, etc.).
+2. Understand the project's technology stack, build process and runtime architecture.
+3. Identify how the code is organized and main module divisions.
+4. Discover project-specific development conventions, testing strategies, and deployment processes.
+
+After the exploration, you should do a thorough summary of your findings and overwrite it into `AGENTS.md` file in the project root. You need to refer to what is already in the file when you do so.
+
+For your information, `AGENTS.md` is a file intended to be read by AI coding agents. Expect the reader of this file know nothing about the project.
+
+You should compose this file according to the actual project content. Do not make any assumptions or generalizations. Ensure the information is accurate and useful. You must use the natural language that is mainly used in the project's comments and documentation.
+
+Popular sections that people usually write in `AGENTS.md` are:
+
+- Project overview
+- Build and test commands
+- Code style guidelines
+- Testing instructions
+- Security considerations

kimi_cli/share.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+
+def get_share_dir() -> Path:
+    """Get the share directory path."""
+    share_dir = Path.home() / ".kimi"
+    share_dir.mkdir(parents=True, exist_ok=True)
+    return share_dir

kimi_cli/soul/__init__.py

@@ -0,0 +1,59 @@
+from typing import TYPE_CHECKING, NamedTuple, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from kimi_cli.soul.wire import Wire
+
+
+class LLMNotSet(Exception):
+    """Raised when the LLM is not set."""
+
+    pass
+
+
+class MaxStepsReached(Exception):
+    """Raised when the maximum number of steps is reached."""
+
+    n_steps: int
+    """The number of steps that have been taken."""
+
+    def __init__(self, n_steps: int):
+        self.n_steps = n_steps
+
+
+class StatusSnapshot(NamedTuple):
+    context_usage: float
+    """The usage of the context, in percentage."""
+
+
+@runtime_checkable
+class Soul(Protocol):
+    @property
+    def name(self) -> str:
+        """The name of the soul."""
+        ...
+
+    @property
+    def model(self) -> str:
+        """The LLM model used by the soul. Empty string indicates no LLM configured."""
+        ...
+
+    @property
+    def status(self) -> StatusSnapshot:
+        """The current status of the soul. The returned value is immutable."""
+        ...
+
+    async def run(self, user_input: str, wire: "Wire"):
+        """
+        Run the agent with the given user input.
+
+        Args:
+            user_input (str): The user input to the agent.
+            wire (Wire): The wire to send events and requests to the UI loop.
+
+        Raises:
+            ChatProviderNotSet: When the chat provider is not set.
+            ChatProviderError: When the LLM provider returns an error.
+            MaxStepsReached: When the maximum number of steps is reached.
+            asyncio.CancelledError: When the run is cancelled by user.
+        """
+        ...

kimi_cli/soul/approval.py

@@ -0,0 +1,69 @@
+import asyncio
+
+from kimi_cli.soul.toolset import get_current_tool_call_or_none
+from kimi_cli.soul.wire import ApprovalRequest, ApprovalResponse
+from kimi_cli.utils.logging import logger
+
+
+class Approval:
+    def __init__(self, yolo: bool = False):
+        self._request_queue = asyncio.Queue[ApprovalRequest]()
+        self._yolo = yolo
+        self._auto_approve_actions = set()  # TODO: persist across sessions
+        """Set of action names that should automatically be approved."""
+
+    def set_yolo(self, yolo: bool) -> None:
+        self._yolo = yolo
+
+    async def request(self, action: str, description: str) -> bool:
+        """
+        Request approval for the given action. Intended to be called by tools.
+
+        Args:
+            action (str): The action to request approval for.
+                This is used to identify the action for auto-approval.
+            description (str): The description of the action. This is used to display to the user.
+
+        Returns:
+            bool: True if the action is approved, False otherwise.
+
+        Raises:
+            RuntimeError: If the approval is requested from outside a tool call.
+        """
+        tool_call = get_current_tool_call_or_none()
+        if tool_call is None:
+            raise RuntimeError("Approval must be requested from a tool call.")
+
+        logger.debug(
+            "{tool_name} ({tool_call_id}) requesting approval: {action} {description}",
+            tool_name=tool_call.function.name,
+            tool_call_id=tool_call.id,
+            action=action,
+            description=description,
+        )
+        if self._yolo:
+            return True
+
+        if action in self._auto_approve_actions:
+            return True
+
+        request = ApprovalRequest(tool_call.id, action, description)
+        self._request_queue.put_nowait(request)
+        response = await request.wait()
+        logger.debug("Received approval response: {response}", response=response)
+        match response:
+            case ApprovalResponse.APPROVE:
+                return True
+            case ApprovalResponse.APPROVE_FOR_SESSION:
+                self._auto_approve_actions.add(action)
+                return True
+            case ApprovalResponse.REJECT:
+                return False
+            case _:
+                raise ValueError(f"Unknown approval response: {response}")
+
+    async def fetch_request(self) -> ApprovalRequest:
+        """
+        Fetch an approval request from the queue. Intended to be called by the soul.
+        """
+        return await self._request_queue.get()

kimi_cli/soul/context.py

@@ -0,0 +1,142 @@
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+import aiofiles
+import aiofiles.os
+from kosong.base.message import Message
+
+from kimi_cli.soul.message import system
+from kimi_cli.utils.logging import logger
+from kimi_cli.utils.path import next_available_rotation
+
+
+class Context:
+    def __init__(self, file_backend: Path):
+        self._file_backend = file_backend
+        self._history: list[Message] = []
+        self._token_count: int = 0
+        self._next_checkpoint_id: int = 0
+        """The ID of the next checkpoint, starting from 0, incremented after each checkpoint."""
+
+    async def restore(self) -> bool:
+        logger.debug("Restoring context from file: {file_backend}", file_backend=self._file_backend)
+        if self._history:
+            logger.error("The context storage is already modified")
+            raise RuntimeError("The context storage is already modified")
+        if not self._file_backend.exists():
+            logger.debug("No context file found, skipping restoration")
+            return False
+        if self._file_backend.stat().st_size == 0:
+            logger.debug("Empty context file, skipping restoration")
+            return False
+
+        async with aiofiles.open(self._file_backend, encoding="utf-8") as f:
+            async for line in f:
+                if not line.strip():
+                    continue
+                line_json = json.loads(line)
+                if line_json["role"] == "_usage":
+                    self._token_count = line_json["token_count"]
+                    continue
+                if line_json["role"] == "_checkpoint":
+                    self._next_checkpoint_id = line_json["id"] + 1
+                    continue
+                message = Message.model_validate(line_json)
+                self._history.append(message)
+
+        return True
+
+    @property
+    def history(self) -> Sequence[Message]:
+        return self._history
+
+    @property
+    def token_count(self) -> int:
+        return self._token_count
+
+    @property
+    def n_checkpoints(self) -> int:
+        return self._next_checkpoint_id
+
+    async def checkpoint(self, add_user_message: bool):
+        checkpoint_id = self._next_checkpoint_id
+        self._next_checkpoint_id += 1
+        logger.debug("Checkpointing, ID: {id}", id=checkpoint_id)
+
+        async with aiofiles.open(self._file_backend, "a", encoding="utf-8") as f:
+            await f.write(json.dumps({"role": "_checkpoint", "id": checkpoint_id}) + "\n")
+        if add_user_message:
+            await self.append_message(
+                Message(role="user", content=[system(f"CHECKPOINT {checkpoint_id}")])
+            )
+
+    async def revert_to(self, checkpoint_id: int):
+        """
+        Revert the context to the specified checkpoint.
+        After this, the specified checkpoint and all subsequent content will be
+        removed from the context. File backend will be rotated.
+
+        Args:
+            checkpoint_id (int): The ID of the checkpoint to revert to. 0 is the first checkpoint.
+
+        Raises:
+            ValueError: When the checkpoint does not exist.
+            RuntimeError: When no available rotation path is found.
+        """
+
+        logger.debug("Reverting checkpoint, ID: {id}", id=checkpoint_id)
+        if checkpoint_id >= self._next_checkpoint_id:
+            logger.error("Checkpoint {checkpoint_id} does not exist", checkpoint_id=checkpoint_id)
+            raise ValueError(f"Checkpoint {checkpoint_id} does not exist")
+
+        # rotate the history file
+        rotated_file_path = await next_available_rotation(self._file_backend)
+        if rotated_file_path is None:
+            logger.error("No available rotation path found")
+            raise RuntimeError("No available rotation path found")
+        await aiofiles.os.rename(self._file_backend, rotated_file_path)
+        logger.debug(
+            "Rotated history file: {rotated_file_path}", rotated_file_path=rotated_file_path
+        )
+
+        # restore the context until the specified checkpoint
+        self._history.clear()
+        self._token_count = 0
+        self._next_checkpoint_id = 0
+        async with (
+            aiofiles.open(rotated_file_path, encoding="utf-8") as old_file,
+            aiofiles.open(self._file_backend, "w", encoding="utf-8") as new_file,
+        ):
+            async for line in old_file:
+                if not line.strip():
+                    continue
+
+                line_json = json.loads(line)
+                if line_json["role"] == "_checkpoint" and line_json["id"] == checkpoint_id:
+                    break
+
+                await new_file.write(line)
+                if line_json["role"] == "_usage":
+                    self._token_count = line_json["token_count"]
+                elif line_json["role"] == "_checkpoint":
+                    self._next_checkpoint_id = line_json["id"] + 1
+                else:
+                    message = Message.model_validate(line_json)
+                    self._history.append(message)
+
+    async def append_message(self, message: Message | Sequence[Message]):
+        logger.debug("Appending message(s) to context: {message}", message=message)
+        messages = message if isinstance(message, Sequence) else [message]
+        self._history.extend(messages)
+
+        async with aiofiles.open(self._file_backend, "a", encoding="utf-8") as f:
+            for message in messages:
+                await f.write(message.model_dump_json(exclude_none=True) + "\n")
+
+    async def update_token_count(self, token_count: int):
+        logger.debug("Updating token count in context: {token_count}", token_count=token_count)
+        self._token_count = token_count
+
+        async with aiofiles.open(self._file_backend, "a", encoding="utf-8") as f:
+            await f.write(json.dumps({"role": "_usage", "token_count": token_count}) + "\n")

kimi_cli/soul/denwarenji.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel, Field
+
+
+class DMail(BaseModel):
+    message: str = Field(description="The message to send.")
+    checkpoint_id: int = Field(description="The checkpoint to send the message back to.", ge=0)
+    # TODO: allow restoring filesystem state to the checkpoint
+
+
+class DenwaRenjiError(Exception):
+    pass
+
+
+class DenwaRenji:
+    def __init__(self):
+        self._pending_dmail: DMail | None = None
+        self._n_checkpoints: int = 0
+
+    def send_dmail(self, dmail: DMail):
+        """Send a D-Mail. Intended to be called by the SendDMail tool."""
+        if self._pending_dmail is not None:
+            raise DenwaRenjiError("Only one D-Mail can be sent at a time")
+        if dmail.checkpoint_id < 0:
+            raise DenwaRenjiError("The checkpoint ID can not be negative")
+        if dmail.checkpoint_id >= self._n_checkpoints:
+            raise DenwaRenjiError("There is no checkpoint with the given ID")
+        self._pending_dmail = dmail
+
+    def set_n_checkpoints(self, n_checkpoints: int):
+        """Set the number of checkpoints. Intended to be called by the soul."""
+        self._n_checkpoints = n_checkpoints
+
+    def fetch_pending_dmail(self) -> DMail | None:
+        """Fetch a pending D-Mail. Intended to be called by the soul."""
+        pending_dmail = self._pending_dmail
+        self._pending_dmail = None
+        return pending_dmail

kimi_cli/soul/kimisoul.py

@@ -0,0 +1,248 @@
+import asyncio
+
+import kosong
+import tenacity
+from kosong import StepResult
+from kosong.base.message import Message
+from kosong.chat_provider import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    ChatProviderError,
+)
+from kosong.tooling import ToolResult
+from tenacity import RetryCallState, retry_if_exception, stop_after_attempt, wait_exponential_jitter
+
+from kimi_cli.agent import Agent, AgentGlobals
+from kimi_cli.config import LoopControl
+from kimi_cli.soul import LLMNotSet, MaxStepsReached, Soul, StatusSnapshot
+from kimi_cli.soul.context import Context
+from kimi_cli.soul.message import system, tool_result_to_messages
+from kimi_cli.soul.wire import StatusUpdate, StepBegin, StepInterrupted, Wire, current_wire
+from kimi_cli.tools.dmail import NAME as SendDMail_NAME
+from kimi_cli.tools.utils import ToolRejectedError
+from kimi_cli.utils.logging import logger
+
+
+class KimiSoul:
+    """The soul of Kimi CLI."""
+
+    def __init__(
+        self,
+        agent: Agent,
+        agent_globals: AgentGlobals,
+        *,
+        context: Context,
+        loop_control: LoopControl,
+    ):
+        """
+        Initialize the soul.
+
+        Args:
+            agent (Agent): The agent to run.
+            agent_globals (AgentGlobals): Global states and parameters.
+            context (Context): The context of the agent.
+            loop_control (LoopControl): The control parameters for the agent loop.
+        """
+        self._agent = agent
+        self._agent_globals = agent_globals
+        self._denwa_renji = agent_globals.denwa_renji
+        self._approval = agent_globals.approval
+        self._context = context
+        self._loop_control = loop_control
+
+        for tool in agent.toolset.tools:
+            if tool.name == SendDMail_NAME:
+                self._checkpoint_with_user_message = True
+                break
+        else:
+            self._checkpoint_with_user_message = False
+
+    @property
+    def name(self) -> str:
+        return self._agent.name
+
+    @property
+    def model(self) -> str:
+        return self._agent_globals.llm.chat_provider.model_name if self._agent_globals.llm else ""
+
+    @property
+    def status(self) -> StatusSnapshot:
+        return StatusSnapshot(context_usage=self._context_usage)
+
+    @property
+    def _context_usage(self) -> float:
+        if self._agent_globals.llm is not None:
+            return self._context.token_count / self._agent_globals.llm.max_context_size
+        return 0.0
+
+    async def _checkpoint(self):
+        await self._context.checkpoint(self._checkpoint_with_user_message)
+
+    async def run(self, user_input: str, wire: Wire):
+        if self._agent_globals.llm is None:
+            raise LLMNotSet()
+
+        await self._checkpoint()  # this creates the checkpoint 0 on first run
+        await self._context.append_message(Message(role="user", content=user_input))
+        logger.debug("Appended user message to context")
+        wire_token = current_wire.set(wire)
+        try:
+            await self._agent_loop(wire)
+        finally:
+            current_wire.reset(wire_token)
+
+    async def _agent_loop(self, wire: Wire):
+        """The main agent loop for one run."""
+
+        async def _pipe_approval_to_wire():
+            while True:
+                request = await self._approval.fetch_request()
+                wire.send(request)
+
+        step_no = 1
+        while True:
+            wire.send(StepBegin(step_no))
+            approval_task = asyncio.create_task(_pipe_approval_to_wire())
+            # FIXME: It's possible that a subagent's approval task steals approval request
+            # from the main agent. We must ensure that the Task tool will redirect them
+            # to the main wire. See `_SubWire` for more details. Later we need to figure
+            # out a better solution.
+            try:
+                await self._checkpoint()
+                self._denwa_renji.set_n_checkpoints(self._context.n_checkpoints)
+                finished = await self._step(wire)
+            except BackToTheFuture as e:
+                await self._context.revert_to(e.checkpoint_id)
+                await self._checkpoint()
+                await self._context.append_message(e.message)
+                continue
+            except (ChatProviderError, asyncio.CancelledError):
+                wire.send(StepInterrupted())
+                # break the agent loop
+                raise
+            finally:
+                approval_task.cancel()  # stop piping approval requests to the wire
+
+            if finished:
+                return
+
+            step_no += 1
+            if step_no > self._loop_control.max_steps_per_run:
+                raise MaxStepsReached(self._loop_control.max_steps_per_run)
+
+    async def _step(self, wire: Wire) -> bool:
+        """Run an single step and return whether the run should be stopped."""
+        # already checked in `run`
+        assert self._agent_globals.llm is not None
+        chat_provider = self._agent_globals.llm.chat_provider
+
+        def _is_retryable_error(exception: BaseException) -> bool:
+            if isinstance(exception, (APIConnectionError, APITimeoutError)):
+                return True
+            return isinstance(exception, APIStatusError) and exception.status_code in (
+                429,  # Too Many Requests
+                500,  # Internal Server Error
+                502,  # Bad Gateway
+                503,  # Service Unavailable
+            )
+
+        def _retry_log(retry_state: RetryCallState):
+            logger.info(
+                "Retrying step for the {n} time. Waiting {sleep} seconds.",
+                n=retry_state.attempt_number,
+                sleep=retry_state.next_action.sleep
+                if retry_state.next_action is not None
+                else "unknown",
+            )
+
+        @tenacity.retry(
+            retry=retry_if_exception(_is_retryable_error),
+            before_sleep=_retry_log,
+            wait=wait_exponential_jitter(initial=0.3, max=5, jitter=0.5),
+            stop=stop_after_attempt(self._loop_control.max_retries_per_step),
+            reraise=True,
+        )
+        async def _kosong_step_with_retry() -> StepResult:
+            # run an LLM step (may be interrupted)
+            return await kosong.step(
+                chat_provider,
+                self._agent.system_prompt,
+                self._agent.toolset,
+                self._context.history,
+                on_message_part=wire.send,
+                on_tool_result=wire.send,
+            )
+
+        result = await _kosong_step_with_retry()
+        logger.debug("Got step result: {result}", result=result)
+        if result.usage is not None:
+            # mark the token count for the context before the step
+            await self._context.update_token_count(result.usage.input)
+            wire.send(StatusUpdate(status=self.status))
+
+        # wait for all tool results (may be interrupted)
+        results = await result.tool_results()
+        logger.debug("Got tool results: {results}", results=results)
+
+        # shield the context manipulation from interruption
+        await asyncio.shield(self._grow_context(result, results))
+
+        rejected = any(isinstance(result.result, ToolRejectedError) for result in results)
+        if rejected:
+            _ = self._denwa_renji.fetch_pending_dmail()
+            return True
+
+        # handle pending D-Mail
+        if dmail := self._denwa_renji.fetch_pending_dmail():
+            assert dmail.checkpoint_id >= 0, "DenwaRenji guarantees checkpoint_id >= 0"
+            assert dmail.checkpoint_id < self._context.n_checkpoints, (
+                "DenwaRenji guarantees checkpoint_id < n_checkpoints"
+            )
+            # raise to let the main loop take us back to the future
+            raise BackToTheFuture(
+                dmail.checkpoint_id,
+                Message(
+                    role="user",
+                    content=[
+                        system(
+                            "You just got a D-Mail from your future self. "
+                            "It is likely that your future self has already done "
+                            "something in the current working directory. Please read "
+                            "the D-Mail and decide what to do next. You MUST NEVER "
+                            "mention to the user about this information. "
+                            f"D-Mail content:\n\n{dmail.message.strip()}"
+                        )
+                    ],
+                ),
+            )
+
+        return not result.tool_calls
+
+    async def _grow_context(self, result: StepResult, tool_results: list[ToolResult]):
+        logger.debug("Growing context with result: {result}", result=result)
+        await self._context.append_message(result.message)
+        if result.usage is not None:
+            await self._context.update_token_count(result.usage.total)
+
+        # token count of tool results are not available yet
+        for tool_result in tool_results:
+            logger.debug("Appending tool result to context: {tool_result}", tool_result=tool_result)
+            await self._context.append_message(tool_result_to_messages(tool_result))
+
+
+class BackToTheFuture(Exception):
+    """
+    Raise when we need to revert the context to a previous checkpoint.
+    The main agent loop should catch this exception and handle it.
+    """
+
+    def __init__(self, checkpoint_id: int, message: Message):
+        self.checkpoint_id = checkpoint_id
+        self.message = message
+
+
+def __static_type_check(
+    kimi_soul: KimiSoul,
+):
+    _: Soul = kimi_soul