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

kimi_cli/acp/AGENTS.md

@@ -0,0 +1,91 @@
+# ACP Integration Notes (kimi-cli)
+
+## Protocol summary (ACP overview)
+- ACP is JSON-RPC 2.0 with request/response methods plus one-way notifications.
+- Typical flow: `initialize` -> optional `authenticate` -> `session/new` or `session/load`
+  -> `session/prompt`
+  with `session/update` notifications and optional `session/cancel`.
+- Clients provide `session/request_permission` and optional terminal/filesystem methods.
+- All ACP file paths must be absolute; line numbers are 1-based.
+
+## Entry points and server modes
+- **Single-session server**: `KimiCLI.run_acp()` uses `ACP` -> `ACPServerSingleSession`.
+  - Code: `src/kimi_cli/app.py`, `src/kimi_cli/ui/acp/__init__.py`.
+  - Used when running CLI with `--acp` UI mode.
+- **Multi-session server**: `acp_main()` runs `ACPServer` with `use_unstable_protocol=True`.
+  - Code: `src/kimi_cli/acp/__init__.py`, `src/kimi_cli/acp/server.py`.
+  - Exposed via the `kimi acp` command in `src/kimi_cli/cli/__init__.py`.
+
+## Capabilities advertised
+- `prompt_capabilities`: `embedded_context=False`, `image=True`, `audio=False`.
+- `mcp_capabilities`: `http=True`, `sse=False`.
+- Single-session: `load_session=False`, no session list capabilities.
+- Multi-session: `load_session=True`, `session_capabilities.list` supported.
+- `auth_methods=[]` (no authentication methods advertised).
+
+## Session lifecycle (implemented behavior)
+- `session/new`
+  - Multi-session: creates a persisted `Session`, builds `KimiCLI`, stores `ACPSession`.
+  - Single-session: wraps the existing `Soul` into a `Wire` loop and creates `ACPSession`.
+  - Both send `AvailableCommandsUpdate` for slash commands on session creation.
+  - MCP servers passed by ACP are converted via `acp_mcp_servers_to_mcp_config`.
+- `session/load`
+  - Multi-session only: loads by `Session.find`, then builds `KimiCLI` and `ACPSession`.
+  - No history replay yet (TODO).
+  - Single-session: not implemented.
+- `session/list`
+  - Multi-session only: lists sessions via `Session.list`, no pagination.
+  - Single-session: not implemented.
+- `session/prompt`
+  - Uses `ACPSession.prompt()` to stream updates and produce a `stop_reason`.
+  - Stop reasons: `end_turn`, `max_turn_requests`, `cancelled`.
+- `session/cancel`
+  - Sets the per-turn cancel event to stop the prompt.
+
+## Streaming updates and content mapping
+- Text chunks -> `AgentMessageChunk`.
+- Think chunks -> `AgentThoughtChunk`.
+- Tool calls:
+  - Start -> `ToolCallStart` with JSON args as text content.
+  - Streaming args -> `ToolCallProgress` with updated title/args.
+  - Results -> `ToolCallProgress` with `completed` or `failed`.
+  - Tool call IDs are prefixed with turn ID to avoid collisions across turns.
+- Plan updates:
+  - `TodoDisplayBlock` is converted into `AgentPlanUpdate`.
+- Available commands:
+  - `AvailableCommandsUpdate` is sent right after session creation.
+
+## Prompt/content conversion
+- Incoming prompt blocks:
+  - Supported: `TextContentBlock`, `ImageContentBlock` (converted to data URL).
+  - Unsupported types are logged and ignored.
+- Tool result display blocks:
+  - `DiffDisplayBlock` -> `FileEditToolCallContent`.
+  - `HideOutputDisplayBlock` suppresses tool output in ACP (used by terminal tool).
+
+## Tool integration and permission flow
+- ACP sessions use `ACPKaos` to route filesystem reads/writes through ACP clients.
+- If the client advertises `terminal` capability, the `Shell` tool is replaced by an
+  ACP-backed `Terminal` tool.
+  - Uses ACP `terminal/create`, waits for exit, streams `TerminalToolCallContent`,
+    then releases the terminal handle.
+- Approval requests in the core tool system are bridged to ACP
+  `session/request_permission` with allow-once/allow-always/reject options.
+
+## Current gaps / not implemented
+- `authenticate` method (not used by current Zed ACP client).
+- `session/set_mode` and `session/set_model` (no multi-mode/model switching in kimi-cli).
+- `ext_method` / `ext_notification` for custom ACP extensions are stubbed.
+- Single-session server does not implement `session/load` or `session/list`.
+
+## Filesystem (ACP client-backed)
+- When the client advertises `fs.readTextFile` / `fs.writeTextFile`, `ACPKaos` routes
+  reads and writes through ACP `fs/*` methods.
+- `ReadFile` uses `KaosPath.read_lines`, which `ACPKaos` implements via ACP reads.
+- `WriteFile` uses `KaosPath.read_text/write_text/append_text` and still generates diffs
+  and approvals in the tool layer.
+
+## Zed-specific notes (as of current integration)
+- Zed does not currently call `authenticate`.
+- Zed’s external agent server session management is not yet available, so
+  `session/load` is not exercised in practice.

kimi_cli/acp/__init__.py

@@ -0,0 +1,13 @@
+def acp_main() -> None:
+    """Entry point for the multi-session ACP server."""
+    import asyncio
+
+    import acp
+
+    from kimi_cli.acp.server import ACPServer
+    from kimi_cli.app import enable_logging
+    from kimi_cli.utils.logging import logger
+
+    enable_logging()
+    logger.info("Starting ACP server on stdio")
+    asyncio.run(acp.run_agent(ACPServer(), use_unstable_protocol=True))

kimi_cli/acp/convert.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import acp
+
+from kimi_cli.acp.types import ACPContentBlock
+from kimi_cli.utils.logging import logger
+from kimi_cli.wire.types import (
+    ContentPart,
+    DiffDisplayBlock,
+    DisplayBlock,
+    ImageURLPart,
+    TextPart,
+    ToolReturnValue,
+)
+
+
+def acp_blocks_to_content_parts(prompt: list[ACPContentBlock]) -> list[ContentPart]:
+    content: list[ContentPart] = []
+    for block in prompt:
+        match block:
+            case acp.schema.TextContentBlock():
+                content.append(TextPart(text=block.text))
+            case acp.schema.ImageContentBlock():
+                content.append(
+                    ImageURLPart(
+                        image_url=ImageURLPart.ImageURL(
+                            url=f"data:{block.mime_type};base64,{block.data}"
+                        )
+                    )
+                )
+            case _:
+                logger.warning("Unsupported prompt content block: {block}", block=block)
+    return content
+
+
+def display_block_to_acp_content(
+    block: DisplayBlock,
+) -> acp.schema.FileEditToolCallContent | None:
+    if isinstance(block, DiffDisplayBlock):
+        return acp.schema.FileEditToolCallContent(
+            type="diff",
+            path=block.path,
+            old_text=block.old_text,
+            new_text=block.new_text,
+        )
+
+    return None
+
+
+def tool_result_to_acp_content(
+    tool_ret: ToolReturnValue,
+) -> list[
+    acp.schema.ContentToolCallContent
+    | acp.schema.FileEditToolCallContent
+    | acp.schema.TerminalToolCallContent
+]:
+    from kimi_cli.acp.tools import HideOutputDisplayBlock
+
+    def _to_acp_content(
+        part: ContentPart,
+    ) -> (
+        acp.schema.ContentToolCallContent
+        | acp.schema.FileEditToolCallContent
+        | acp.schema.TerminalToolCallContent
+    ):
+        if isinstance(part, TextPart):
+            return acp.schema.ContentToolCallContent(
+                type="content", content=acp.schema.TextContentBlock(type="text", text=part.text)
+            )
+        logger.warning("Unsupported content part in tool result: {part}", part=part)
+        return acp.schema.ContentToolCallContent(
+            type="content",
+            content=acp.schema.TextContentBlock(type="text", text=f"[{part.__class__.__name__}]"),
+        )
+
+    def _to_text_block(text: str) -> acp.schema.ContentToolCallContent:
+        return acp.schema.ContentToolCallContent(
+            type="content", content=acp.schema.TextContentBlock(type="text", text=text)
+        )
+
+    contents: list[
+        acp.schema.ContentToolCallContent
+        | acp.schema.FileEditToolCallContent
+        | acp.schema.TerminalToolCallContent
+    ] = []
+
+    for block in tool_ret.display:
+        if isinstance(block, HideOutputDisplayBlock):
+            # return early to indicate no output should be shown
+            return []
+
+        content = display_block_to_acp_content(block)
+        if content is not None:
+            contents.append(content)
+    # TODO: better concatenation of `display` blocks and `output`?
+
+    output = tool_ret.output
+    if isinstance(output, str):
+        if output:
+            contents.append(_to_text_block(output))
+    else:
+        # NOTE: At the moment, ToolReturnValue.output is either a string or a
+        # list of ContentPart. We avoid an unnecessary isinstance() check here
+        # to keep pyright happy while still handling list outputs.
+        contents.extend(_to_acp_content(part) for part in output)
+
+    if not contents and tool_ret.message:
+        # Fallback to the `message` for LLM if there's no other content
+        contents.append(_to_text_block(tool_ret.message))
+
+    return contents

kimi_cli/acp/kaos.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Iterable
+from contextlib import suppress
+from typing import Literal
+
+import acp
+from kaos import AsyncReadable, AsyncWritable, Kaos, KaosProcess, StatResult, StrOrKaosPath
+from kaos.local import local_kaos
+from kaos.path import KaosPath
+
+_DEFAULT_TERMINAL_OUTPUT_LIMIT = 50_000
+_DEFAULT_POLL_INTERVAL = 0.2
+_TRUNCATION_NOTICE = "[acp output truncated]\n"
+
+
+class _NullWritable:
+    def can_write_eof(self) -> bool:
+        return False
+
+    def close(self) -> None:
+        return None
+
+    async def drain(self) -> None:
+        return None
+
+    def is_closing(self) -> bool:
+        return False
+
+    async def wait_closed(self) -> None:
+        return None
+
+    def write(self, data: bytes) -> None:
+        return None
+
+    def writelines(self, data: Iterable[bytes], /) -> None:
+        return None
+
+    def write_eof(self) -> None:
+        return None
+
+
+class ACPProcess:
+    """KAOS process adapter for ACP terminal execution."""
+
+    def __init__(
+        self,
+        terminal: acp.TerminalHandle,
+        *,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self._terminal = terminal
+        self._poll_interval = poll_interval
+        self._stdin = _NullWritable()
+        self._stdout = asyncio.StreamReader()
+        self._stderr = asyncio.StreamReader()
+        self.stdin: AsyncWritable = self._stdin
+        self.stdout: AsyncReadable = self._stdout
+        # ACP does not expose stderr separately; keep stderr empty.
+        self.stderr: AsyncReadable = self._stderr
+        self._returncode: int | None = None
+        self._last_output = ""
+        self._truncation_noted = False
+        self._exit_future: asyncio.Future[int] = asyncio.get_running_loop().create_future()
+        self._poll_task = asyncio.create_task(self._poll_output())
+
+    @property
+    def pid(self) -> int:
+        return -1
+
+    @property
+    def returncode(self) -> int | None:
+        return self._returncode
+
+    async def wait(self) -> int:
+        return await self._exit_future
+
+    async def kill(self) -> None:
+        await self._terminal.kill()
+
+    def _feed_output(self, output_response: acp.schema.TerminalOutputResponse) -> None:
+        output = output_response.output
+        reset = output_response.truncated or (
+            self._last_output and not output.startswith(self._last_output)
+        )
+        if reset and self._last_output and not self._truncation_noted:
+            self._stdout.feed_data(_TRUNCATION_NOTICE.encode("utf-8"))
+            self._truncation_noted = True
+
+        delta = output if reset else output[len(self._last_output) :]
+        if delta:
+            self._stdout.feed_data(delta.encode("utf-8", "replace"))
+        self._last_output = output
+
+    @staticmethod
+    def _normalize_exit_code(exit_code: int | None) -> int:
+        return 1 if exit_code is None else exit_code
+
+    async def _poll_output(self) -> None:
+        exit_task = asyncio.create_task(self._terminal.wait_for_exit())
+        exit_code: int | None = None
+        try:
+            while True:
+                if exit_task.done():
+                    exit_response = exit_task.result()
+                    exit_code = exit_response.exit_code
+                    break
+
+                output_response = await self._terminal.current_output()
+                self._feed_output(output_response)
+                if output_response.exit_status:
+                    exit_code = output_response.exit_status.exit_code
+                    try:
+                        exit_response = await exit_task
+                        exit_code = exit_response.exit_code or exit_code
+                    except Exception:
+                        pass
+                    break
+
+                await asyncio.sleep(self._poll_interval)
+
+            final_output = await self._terminal.current_output()
+            self._feed_output(final_output)
+        except Exception as exc:
+            error_note = f"[acp terminal error] {exc}\n"
+            self._stdout.feed_data(error_note.encode("utf-8", "replace"))
+            if exit_code is None:
+                exit_code = 1
+        finally:
+            if not exit_task.done():
+                exit_task.cancel()
+                with suppress(Exception):
+                    await exit_task
+            self._returncode = self._normalize_exit_code(exit_code)
+            self._stdout.feed_eof()
+            self._stderr.feed_eof()
+            if not self._exit_future.done():
+                self._exit_future.set_result(self._returncode)
+            with suppress(Exception):
+                await self._terminal.release()
+
+
+class ACPKaos:
+    """KAOS backend that routes supported operations through ACP."""
+
+    name: str = "acp"
+
+    def __init__(
+        self,
+        client: acp.Client,
+        session_id: str,
+        client_capabilities: acp.schema.ClientCapabilities | None,
+        fallback: Kaos | None = None,
+        *,
+        output_byte_limit: int | None = _DEFAULT_TERMINAL_OUTPUT_LIMIT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self._client = client
+        self._session_id = session_id
+        self._fallback = fallback or local_kaos
+        fs = client_capabilities.fs if client_capabilities else None
+        self._supports_read = bool(fs and fs.read_text_file)
+        self._supports_write = bool(fs and fs.write_text_file)
+        self._supports_terminal = bool(client_capabilities and client_capabilities.terminal)
+        self._output_byte_limit = output_byte_limit
+        self._poll_interval = poll_interval
+
+    def pathclass(self):
+        return self._fallback.pathclass()
+
+    def normpath(self, path: StrOrKaosPath) -> KaosPath:
+        return self._fallback.normpath(path)
+
+    def gethome(self) -> KaosPath:
+        return self._fallback.gethome()
+
+    def getcwd(self) -> KaosPath:
+        return self._fallback.getcwd()
+
+    async def chdir(self, path: StrOrKaosPath) -> None:
+        await self._fallback.chdir(path)
+
+    async def stat(self, path: StrOrKaosPath, *, follow_symlinks: bool = True) -> StatResult:
+        return await self._fallback.stat(path, follow_symlinks=follow_symlinks)
+
+    def iterdir(self, path: StrOrKaosPath) -> AsyncGenerator[KaosPath]:
+        return self._fallback.iterdir(path)
+
+    def glob(
+        self, path: StrOrKaosPath, pattern: str, *, case_sensitive: bool = True
+    ) -> AsyncGenerator[KaosPath]:
+        return self._fallback.glob(path, pattern, case_sensitive=case_sensitive)
+
+    async def readbytes(self, path: StrOrKaosPath, n: int | None = None) -> bytes:
+        return await self._fallback.readbytes(path, n=n)
+
+    async def readtext(
+        self,
+        path: StrOrKaosPath,
+        *,
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> str:
+        abs_path = self._abs_path(path)
+        if not self._supports_read:
+            return await self._fallback.readtext(abs_path, encoding=encoding, errors=errors)
+        response = await self._client.read_text_file(path=abs_path, session_id=self._session_id)
+        return response.content
+
+    async def readlines(
+        self,
+        path: StrOrKaosPath,
+        *,
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> AsyncGenerator[str]:
+        text = await self.readtext(path, encoding=encoding, errors=errors)
+        for line in text.splitlines(keepends=True):
+            yield line
+
+    async def writebytes(self, path: StrOrKaosPath, data: bytes) -> int:
+        return await self._fallback.writebytes(path, data)
+
+    async def writetext(
+        self,
+        path: StrOrKaosPath,
+        data: str,
+        *,
+        mode: Literal["w", "a"] = "w",
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> int:
+        abs_path = self._abs_path(path)
+        if mode == "a":
+            if self._supports_read and self._supports_write:
+                existing = await self.readtext(abs_path, encoding=encoding, errors=errors)
+                await self._client.write_text_file(
+                    path=abs_path,
+                    content=existing + data,
+                    session_id=self._session_id,
+                )
+                return len(data)
+            return await self._fallback.writetext(
+                abs_path, data, mode="a", encoding=encoding, errors=errors
+            )
+
+        if not self._supports_write:
+            return await self._fallback.writetext(
+                abs_path, data, mode=mode, encoding=encoding, errors=errors
+            )
+
+        await self._client.write_text_file(
+            path=abs_path,
+            content=data,
+            session_id=self._session_id,
+        )
+        return len(data)
+
+    async def mkdir(
+        self, path: StrOrKaosPath, parents: bool = False, exist_ok: bool = False
+    ) -> None:
+        await self._fallback.mkdir(path, parents=parents, exist_ok=exist_ok)
+
+    async def exec(self, *args: str) -> KaosProcess:
+        return await self._fallback.exec(*args)
+
+    def _abs_path(self, path: StrOrKaosPath) -> str:
+        kaos_path = path if isinstance(path, KaosPath) else KaosPath(path)
+        return str(kaos_path.canonical())

kimi_cli/acp/mcp.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+import acp.schema
+from fastmcp.mcp_config import MCPConfig
+from pydantic import ValidationError
+
+from kimi_cli.acp.types import MCPServer
+from kimi_cli.exception import MCPConfigError
+
+
+def acp_mcp_servers_to_mcp_config(mcp_servers: list[MCPServer]) -> MCPConfig:
+    if not mcp_servers:
+        return MCPConfig()
+
+    try:
+        return MCPConfig.model_validate(
+            {"mcpServers": {server.name: _convert_acp_mcp_server(server) for server in mcp_servers}}
+        )
+    except ValidationError as exc:
+        raise MCPConfigError(f"Invalid MCP config from ACP client: {exc}") from exc
+
+
+def _convert_acp_mcp_server(server: MCPServer) -> dict[str, Any]:
+    """Convert an ACP MCP server to a dictionary representation."""
+    match server:
+        case acp.schema.HttpMcpServer():
+            return {
+                "url": server.url,
+                "transport": "http",
+                "headers": {header.name: header.value for header in server.headers},
+            }
+        case acp.schema.SseMcpServer():
+            return {
+                "url": server.url,
+                "transport": "sse",
+                "headers": {header.name: header.value for header in server.headers},
+            }
+        case acp.schema.McpServerStdio():
+            return {
+                "command": server.command,
+                "args": server.args,
+                "env": {item.name: item.value for item in server.env},
+                "transport": "stdio",
+            }