kimi-cli 0.45__py3-none-any.whl → 0.47__py3-none-any.whl

kimi_cli/ui/wire/README.md

@@ -0,0 +1,109 @@
+# Wire over STDIO
+
+Learn how `WireServer` (src/kimi_cli/ui/wire/__init__.py) exposes the Soul runtime over stdio.
+Use this reference when building clients or SDKs.
+
+## Transport
+- The server acquires stdio streams via `acp.stdio_streams()` and stays alive until stdin closes.
+- Messages use newline-delimited JSON. Each object must include `"jsonrpc": "2.0"`.
+- Outbound JSON is UTF-8 encoded with compact separators `(",", ":")`.
+
+## Lifecycle
+1. A client launches `kimi` (or another entry point) with the wire UI enabled.
+2. `WireServer.run()` spawns a reader loop on stdin and a writer loop draining an internal queue.
+3. Incoming payloads are validated by `JSONRPC_MESSAGE_ADAPTER`; invalid objects only log warnings.
+4. The Soul uses `Wire` (src/kimi_cli/wire/__init__.py); the UI forwards every message as JSON-RPC.
+5. EOF on stdin or a fatal error cancels the Soul, rejects approvals, and closes stdout.
+
+## Client → Server calls
+
+### `run`
+- Request:
+  ```json
+  {"jsonrpc": "2.0", "id": "<request-id>", "method": "run", "params": {"input": "<prompt>"}}
+  ```
+  `params.prompt` is accepted as an alias for `params.input`.
+- Success results:
+  - `{"status": "finished"}` when the run completes.
+  - `{"status": "cancelled"}` when either side interrupts.
+  - `{"status": "max_steps_reached", "steps": <int>}` when the step limit triggers.
+- Error codes:
+  - `-32000`: A run is already in progress.
+  - `-32602`: The `input` or `prompt` parameter is missing or not a string.
+  - `-32001`: LLM is not configured.
+  - `-32002`: The chat provider reported an error.
+  - `-32003`: The requested LLM is unsupported.
+  - `-32099`: An unhandled exception occurred during the run.
+
+### `interrupt`
+- Request:
+  ```json
+  {"jsonrpc": "2.0", "id": "<request-id>", "method": "interrupt", "params": {}}
+  ```
+  The `id` field is optional; omitting it turns the request into a notification.
+- Success results:
+  - `{"status": "ok"}` when a running Soul acknowledges the interrupt.
+  - `{"status": "idle"}` when no run is active.
+- Interrupt requests never raise protocol errors.
+
+## Server → Client traffic
+
+### Event notifications
+Events are JSON-RPC notifications with method `event` and no `id`.
+Payloads come from `serialize_event` (src/kimi_cli/wire/message.py):
+- `step_begin`: payload `{"n": <int>}` with the 1-based step counter.
+- `step_interrupted`: no payload; the Soul paused mid-step.
+- `compaction_begin`: no payload; a compaction pass started.
+- `compaction_end`: no payload; always follows `compaction_begin`.
+- `status_update`: payload `{"context_usage": <int>}` from `StatusSnapshot`.
+- `content_part`: JSON object produced by `ContentPart.model_dump(mode="json", exclude_none=True)`.
+- `tool_call`: JSON object produced by `ToolCall.model_dump(mode="json", exclude_none=True)`.
+- `tool_call_part`: JSON object from `ToolCallPart.model_dump(mode="json", exclude_none=True)`.
+- `tool_result`: object with `tool_call_id`, `ok`, and `result` (`output`, `message`, `brief`).
+  When `ok` is true the `output` may be text, a JSON object, or an array of JSON objects for
+  multi-part content.
+
+Event order mirrors Soul execution because the server uses an `asyncio.Queue` for FIFO delivery.
+
+### Approval requests
+- Approval prompts use method `request`; their `id` equals the UUID in `ApprovalRequest.id`:
+  ```json
+  {
+    "jsonrpc": "2.0",
+    "id": "<approval-id>",
+    "method": "request",
+    "params": {
+      "type": "approval",
+      "payload": {
+        "id": "<approval-id>",
+        "tool_call_id": "<tool-call-id>",
+        "sender": "<agent>",
+        "action": "<action>",
+        "description": "<human readable context>"
+      }
+    }
+  }
+  ```
+- Clients reply with JSON-RPC success.
+  `result.response` must be `approve`, `approve_for_session`, or `reject`:
+  ```json
+  {"jsonrpc": "2.0", "id": "<approval-id>", "result": {"response": "approve"}}
+  ```
+- Error responses or unknown values are interpreted as rejection.
+- Unanswered approvals are auto-rejected during server shutdown.
+
+## Error responses from the server
+Errors follow JSON-RPC semantics.
+The error object includes `code` and `message`.
+Custom codes live in the `-320xx` range.
+Clients should allow an optional `data` field even though the server omits it today.
+
+## Shutdown semantics
+- Shutdown cancels runs, stops the writer queue, rejects pending approvals, and closes stdout.
+- EOF on stdout signals process exit; clients can treat it as terminal.
+
+## Implementation notes for SDK authors
+- Only one `run` call may execute at a time; queue additional runs client side.
+- The payloads for `content_part`, `tool_call`, and `tool_call_part` already contain JSON objects.
+- Approval handling is synchronous; always send a response even if the user cancels.
+- Logging is verbose for non-stream messages; unknown methods are ignored for forward compatibility.

kimi_cli/ui/wire/__init__.py

@@ -0,0 +1,340 @@
+import asyncio
+import contextlib
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+import acp  # pyright: ignore[reportMissingTypeStubs]
+from kosong.chat_provider import ChatProviderError
+from pydantic import ValidationError
+
+from kimi_cli.soul import LLMNotSet, LLMNotSupported, MaxStepsReached, RunCancelled, Soul, run_soul
+from kimi_cli.utils.logging import logger
+from kimi_cli.wire import WireUISide
+from kimi_cli.wire.message import (
+    ApprovalRequest,
+    ApprovalResponse,
+    Event,
+    serialize_approval_request,
+    serialize_event,
+)
+
+from .jsonrpc import (
+    JSONRPC_MESSAGE_ADAPTER,
+    JSONRPC_VERSION,
+    JSONRPCErrorResponse,
+    JSONRPCRequest,
+    JSONRPCSuccessResponse,
+)
+
+_ResultKind = Literal["ok", "error"]
+
+
+class _SoulRunner:
+    def __init__(
+        self,
+        soul: Soul,
+        send_event: Callable[[Event], Awaitable[None]],
+        request_approval: Callable[[ApprovalRequest], Awaitable[ApprovalResponse]],
+    ):
+        self._soul = soul
+        self._send_event = send_event
+        self._request_approval = request_approval
+        self._cancel_event: asyncio.Event | None = None
+        self._task: asyncio.Task[tuple[_ResultKind, Any]] | None = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    async def run(self, user_input: str) -> tuple[_ResultKind, Any]:
+        if self.is_running:
+            raise RuntimeError("Soul is already running")
+
+        self._cancel_event = asyncio.Event()
+        self._task = asyncio.create_task(self._run(user_input))
+        try:
+            return await self._task
+        finally:
+            self._task = None
+            self._cancel_event = None
+
+    async def interrupt(self) -> None:
+        if self._cancel_event is not None:
+            self._cancel_event.set()
+
+    async def shutdown(self) -> None:
+        await self.interrupt()
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+            self._cancel_event = None
+
+    async def _run(self, user_input: str) -> tuple[_ResultKind, Any]:
+        assert self._cancel_event is not None
+        try:
+            await run_soul(
+                self._soul,
+                user_input,
+                self._ui_loop,
+                self._cancel_event,
+            )
+        except LLMNotSet:
+            return ("error", (-32001, "LLM is not configured"))
+        except LLMNotSupported as e:
+            return ("error", (-32003, f"LLM not supported: {e}"))
+        except ChatProviderError as e:
+            return ("error", (-32002, f"LLM provider error: {e}"))
+        except MaxStepsReached as e:
+            return ("ok", {"status": "max_steps_reached", "steps": e.n_steps})
+        except RunCancelled:
+            return ("ok", {"status": "cancelled"})
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.exception("Soul run failed:")
+            return ("error", (-32099, f"Run failed: {e}"))
+        return ("ok", {"status": "finished"})
+
+    async def _ui_loop(self, wire: WireUISide) -> None:
+        while True:
+            message = await wire.receive()
+            if isinstance(message, ApprovalRequest):
+                response = await self._request_approval(message)
+                message.resolve(response)
+            else:
+                # must be Event
+                await self._send_event(message)
+
+
+class WireServer:
+    def __init__(self, soul: Soul):
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._write_task: asyncio.Task[None] | None = None
+        self._send_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._pending_requests: dict[str, ApprovalRequest] = {}
+        self._runner = _SoulRunner(
+            soul,
+            send_event=self._send_event,
+            request_approval=self._request_approval,
+        )
+
+    async def run(self) -> bool:
+        logger.info("Starting Wire server on stdio")
+
+        self._reader, self._writer = await acp.stdio_streams()
+        self._write_task = asyncio.create_task(self._write_loop())
+        try:
+            await self._read_loop()
+        finally:
+            await self._shutdown()
+
+        return True
+
+    async def _read_loop(self) -> None:
+        assert self._reader is not None
+
+        while True:
+            line = await self._reader.readline()
+            if not line:
+                logger.info("stdin closed, Wire server exiting")
+                break
+
+            try:
+                payload = json.loads(line.decode("utf-8"))
+            except json.JSONDecodeError:
+                logger.warning("Invalid JSON line: {line}", line=line)
+                continue
+
+            await self._dispatch(payload)
+
+    async def _dispatch(self, payload: dict[str, Any]) -> None:
+        version = payload.get("jsonrpc")
+        if version != JSONRPC_VERSION:
+            logger.warning("Unexpected jsonrpc version: {version}", version=version)
+            return
+
+        try:
+            message = JSONRPC_MESSAGE_ADAPTER.validate_python(payload)
+        except ValidationError as e:
+            logger.warning(
+                "Ignoring malformed JSON-RPC payload: {message}; error={error}",
+                message=payload,
+                error=str(e),
+            )
+            return
+
+        match message:
+            case JSONRPCRequest():
+                await self._handle_request(message)
+            case JSONRPCSuccessResponse() | JSONRPCErrorResponse():
+                await self._handle_response(message)
+
+    async def _handle_request(self, message: JSONRPCRequest) -> None:
+        method = message.method
+        msg_id = message.id
+        params = message.params
+
+        if method == "run":
+            await self._handle_run(msg_id, params)
+        elif method == "interrupt":
+            await self._handle_interrupt(msg_id)
+        else:
+            logger.warning("Unknown method: {method}", method=method)
+            if msg_id is not None:
+                await self._send_error(msg_id, -32601, f"Unknown method: {method}")
+
+    async def _handle_response(
+        self,
+        message: JSONRPCSuccessResponse | JSONRPCErrorResponse,
+    ) -> None:
+        msg_id = message.id
+        if msg_id is None:
+            logger.warning("Response without id: {message}", message=message.model_dump())
+            return
+
+        pending = self._pending_requests.get(msg_id)
+        if pending is None:
+            logger.warning("No pending request for response id={id}", id=msg_id)
+            return
+
+        try:
+            if isinstance(message, JSONRPCErrorResponse):
+                pending.resolve(ApprovalResponse.REJECT)
+            else:
+                response = self._parse_approval_response(message.result)
+                pending.resolve(response)
+        finally:
+            self._pending_requests.pop(msg_id, None)
+
+    async def _handle_run(self, msg_id: Any, params: dict[str, Any]) -> None:
+        if msg_id is None:
+            logger.warning("Run notification ignored")
+            return
+
+        if self._runner.is_running:
+            await self._send_error(msg_id, -32000, "Run already in progress")
+            return
+
+        user_input = params.get("input")
+        if not isinstance(user_input, str):
+            user_input = params.get("prompt")
+        if not isinstance(user_input, str):
+            await self._send_error(msg_id, -32602, "`input` (or `prompt`) must be a string")
+            return
+
+        try:
+            kind, payload = await self._runner.run(user_input)
+        except RuntimeError:
+            await self._send_error(msg_id, -32000, "Run already in progress")
+            return
+
+        if kind == "error":
+            code, message = payload
+            await self._send_error(msg_id, code, message)
+        else:
+            await self._send_response(msg_id, payload)
+
+    async def _handle_interrupt(self, msg_id: Any) -> None:
+        if not self._runner.is_running:
+            if msg_id is not None:
+                await self._send_response(msg_id, {"status": "idle"})
+            return
+
+        await self._runner.interrupt()
+        if msg_id is not None:
+            await self._send_response(msg_id, {"status": "ok"})
+
+    async def _send_event(self, event: Event) -> None:
+        await self._send_notification("event", serialize_event(event))
+
+    async def _request_approval(self, request: ApprovalRequest) -> ApprovalResponse:
+        self._pending_requests[request.id] = request
+
+        await self._send_request(
+            request.id,
+            "request",
+            {"type": "approval", "payload": serialize_approval_request(request)},
+        )
+
+        try:
+            return await request.wait()
+        finally:
+            self._pending_requests.pop(request.id, None)
+
+    def _parse_approval_response(self, result: dict[str, Any]) -> ApprovalResponse:
+        value = result.get("response")
+        try:
+            if isinstance(value, ApprovalResponse):
+                return value
+            return ApprovalResponse(str(value))
+        except ValueError:
+            logger.warning("Unknown approval response: {value}", value=value)
+            return ApprovalResponse.REJECT
+
+    async def _write_loop(self) -> None:
+        assert self._writer is not None
+
+        try:
+            while True:
+                try:
+                    payload = await self._send_queue.get()
+                except asyncio.QueueShutDown:
+                    logger.debug("Send queue shut down, stopping Wire server write loop")
+                    break
+                data = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+                self._writer.write(data.encode("utf-8") + b"\n")
+                await self._writer.drain()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("Wire server write loop error:")
+            raise
+
+    async def _send_notification(self, method: str, params: Any) -> None:
+        await self._enqueue_payload(
+            {"jsonrpc": JSONRPC_VERSION, "method": method, "params": params}
+        )
+
+    async def _send_request(self, msg_id: Any, method: str, params: Any) -> None:
+        await self._enqueue_payload(
+            {"jsonrpc": JSONRPC_VERSION, "id": msg_id, "method": method, "params": params}
+        )
+
+    async def _send_response(self, msg_id: Any, result: Any) -> None:
+        await self._enqueue_payload({"jsonrpc": JSONRPC_VERSION, "id": msg_id, "result": result})
+
+    async def _send_error(self, msg_id: Any, code: int, message: str) -> None:
+        await self._enqueue_payload(
+            {"jsonrpc": JSONRPC_VERSION, "id": msg_id, "error": {"code": code, "message": message}}
+        )
+
+    async def _enqueue_payload(self, payload: dict[str, Any]) -> None:
+        try:
+            await self._send_queue.put(payload)
+        except asyncio.QueueShutDown:
+            logger.debug("Send queue shut down; dropping payload: {payload}", payload=payload)
+
+    async def _shutdown(self) -> None:
+        await self._runner.shutdown()
+        self._send_queue.shutdown()
+
+        if self._write_task is not None:
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._write_task
+
+        for request in self._pending_requests.values():
+            if not request.resolved:
+                request.resolve(ApprovalResponse.REJECT)
+        self._pending_requests.clear()
+
+        if self._writer is not None:
+            self._writer.close()
+            with contextlib.suppress(Exception):
+                await self._writer.wait_closed()
+            self._writer = None
+
+        self._reader = None

kimi_cli/ui/wire/jsonrpc.py

@@ -0,0 +1,48 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+JSONRPC_VERSION = "2.0"
+
+
+class _MessageBase(BaseModel):
+    jsonrpc: Literal["2.0"]
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class JSONRPCRequest(_MessageBase):
+    method: str
+    id: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class _ResponseBase(_MessageBase):
+    id: str | None
+
+
+class JSONRPCSuccessResponse(_ResponseBase):
+    result: dict[str, Any]
+
+
+class JSONRPCErrorObject(BaseModel):
+    code: int
+    message: str
+    data: Any | None = None
+
+
+class JSONRPCErrorResponse(_ResponseBase):
+    error: JSONRPCErrorObject
+
+
+JSONRPCMessage = JSONRPCRequest | JSONRPCSuccessResponse | JSONRPCErrorResponse
+JSONRPC_MESSAGE_ADAPTER = TypeAdapter[JSONRPCMessage](JSONRPCMessage)
+
+__all__ = [
+    "JSONRPCRequest",
+    "JSONRPCSuccessResponse",
+    "JSONRPCErrorObject",
+    "JSONRPCErrorResponse",
+    "JSONRPCMessage",
+    "JSONRPC_MESSAGE_ADAPTER",
+]

kimi_cli/utils/clipboard.py

@@ -0,0 +1,10 @@
+import pyperclip
+
+
+def is_clipboard_available() -> bool:
+    """Check if the Pyperclip clipboard is available."""
+    try:
+        pyperclip.paste()
+        return True
+    except Exception:
+        return False

kimi_cli/wire/message.py

@@ -1,10 +1,11 @@
 import asyncio
 import uuid
+from collections.abc import Sequence
 from enum import Enum
-from typing import TYPE_CHECKING, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from kosong.base.message import ContentPart, ToolCall, ToolCallPart
-from kosong.tooling import ToolResult
+from kosong.tooling import ToolOk, ToolResult
 
 if TYPE_CHECKING:
     from kimi_cli.soul import StatusSnapshot
@@ -89,3 +90,89 @@ class ApprovalRequest:
 
 
 type WireMessage = Event | ApprovalRequest
+
+
+def serialize_event(event: Event) -> dict[str, Any]:
+    """
+    Convert an event message into a JSON-serializable dictionary.
+    """
+    match event:
+        case StepBegin():
+            return {"type": "step_begin", "payload": {"n": event.n}}
+        case StepInterrupted():
+            return {"type": "step_interrupted"}
+        case CompactionBegin():
+            return {"type": "compaction_begin"}
+        case CompactionEnd():
+            return {"type": "compaction_end"}
+        case StatusUpdate():
+            return {
+                "type": "status_update",
+                "payload": {"context_usage": event.status.context_usage},
+            }
+        case ContentPart():
+            return {
+                "type": "content_part",
+                "payload": event.model_dump(mode="json", exclude_none=True),
+            }
+        case ToolCall():
+            return {
+                "type": "tool_call",
+                "payload": event.model_dump(mode="json", exclude_none=True),
+            }
+        case ToolCallPart():
+            return {
+                "type": "tool_call_part",
+                "payload": event.model_dump(mode="json", exclude_none=True),
+            }
+        case ToolResult():
+            return {
+                "type": "tool_result",
+                "payload": serialize_tool_result(event),
+            }
+
+
+def serialize_approval_request(request: ApprovalRequest) -> dict[str, Any]:
+    """
+    Convert an ApprovalRequest into a JSON-serializable dictionary.
+    """
+    return {
+        "id": request.id,
+        "tool_call_id": request.tool_call_id,
+        "sender": request.sender,
+        "action": request.action,
+        "description": request.description,
+    }
+
+
+def serialize_tool_result(result: ToolResult) -> dict[str, Any]:
+    if isinstance(result.result, ToolOk):
+        ok = True
+        result_data = {
+            "output": _serialize_tool_output(result.result.output),
+            "message": result.result.message,
+            "brief": result.result.brief,
+        }
+    else:
+        ok = False
+        result_data = {
+            "output": result.result.output,
+            "message": result.result.message,
+            "brief": result.result.brief,
+        }
+    return {
+        "tool_call_id": result.tool_call_id,
+        "ok": ok,
+        "result": result_data,
+    }
+
+
+def _serialize_tool_output(
+    output: str | ContentPart | Sequence[ContentPart],
+) -> str | list[Any] | dict[str, Any]:
+    if isinstance(output, str):
+        return output
+    elif isinstance(output, ContentPart):
+        return output.model_dump(mode="json", exclude_none=True)
+    else:  # Sequence[ContentPart]
+        return [part.model_dump(mode="json", exclude_none=True) for part in output]

{kimi_cli-0.45.dist-info → kimi_cli-0.47.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.3
 Name: kimi-cli
-Version: 0.45
+Version: 0.47
 Summary: Kimi CLI is your next CLI agent.
-Requires-Dist: agent-client-protocol==0.6.2
+Requires-Dist: agent-client-protocol==0.6.3
 Requires-Dist: aiofiles==25.1.0
 Requires-Dist: aiohttp==3.13.2
 Requires-Dist: click==8.3.0
-Requires-Dist: kosong==0.16.2
+Requires-Dist: kosong==0.17.0
 Requires-Dist: loguru==0.7.3
 Requires-Dist: patch-ng==1.19.0
 Requires-Dist: prompt-toolkit==3.0.52
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 [![Checks](https://img.shields.io/github/check-runs/MoonshotAI/kimi-cli/main)](https://github.com/MoonshotAI/kimi-cli/actions)
 [![Version](https://img.shields.io/pypi/v/kimi-cli)](https://pypi.org/project/kimi-cli/)
 [![Downloads](https://img.shields.io/pypi/dw/kimi-cli)](https://pypistats.org/packages/kimi-cli)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/MoonshotAI/kimi-cli)
 
 [中文](https://www.kimi.com/coding/docs/kimi-cli.html)