kimi-agent-sdk-x 0.0.5__tar.gz

kimi_agent_sdk_x-0.0.5/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.3
+Name: kimi-agent-sdk-x
+Version: 0.0.5
+Summary: A Python SDK for Kimi Agent (Kimi CLI).
+Keywords: kimi,agent,sdk,coding-agents,llm,automation
+Author: Moonshot AI
+Author-email: Moonshot AI <team@moonshot.ai>
+License: Apache-2.0
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Dist: kimi-cli-x>=1.12.0,<1.13.0
+Requires-Dist: kosong>=0.42.0,<0.43.0
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/MoonshotAI/kimi-agent-sdk/blob/main/python/CHANGELOG.md
+Project-URL: Documentation, https://github.com/MoonshotAI/kimi-agent-sdk/tree/main/README.md
+Project-URL: Homepage, https://github.com/MoonshotAI/kimi-agent-sdk
+Project-URL: Issues, https://github.com/MoonshotAI/kimi-agent-sdk/issues
+Project-URL: Repository, https://github.com/MoonshotAI/kimi-agent-sdk
+Description-Content-Type: text/markdown
+
+# Kimi Agent SDK for Python
+
+Python SDK for programmatically controlling the Kimi CLI (Kimi Code) agent runtime. Use it to run sessions, stream responses, and handle approvals from Python applications.
+
+Quick start: [guides/python/quickstart.md](../guides/python/quickstart.md)

kimi_agent_sdk_x-0.0.5/README.md

@@ -0,0 +1,5 @@
+# Kimi Agent SDK for Python
+
+Python SDK for programmatically controlling the Kimi CLI (Kimi Code) agent runtime. Use it to run sessions, stream responses, and handle approvals from Python applications.
+
+Quick start: [guides/python/quickstart.md](../guides/python/quickstart.md)

kimi_agent_sdk_x-0.0.5/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "kimi-agent-sdk-x"
+version = "0.0.5"
+description = "A Python SDK for Kimi Agent (Kimi CLI)."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+keywords = ["kimi", "agent", "sdk", "coding-agents", "llm", "automation"]
+authors = [{ name = "Moonshot AI", email = "team@moonshot.ai" }]
+classifiers = [
+    "Typing :: Typed",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: Apache Software License",
+]
+dependencies = [
+    "kimi-cli-x>=1.12.0,<1.13.0",
+    "kosong>=0.42.0,<0.43.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/MoonshotAI/kimi-agent-sdk"
+Repository = "https://github.com/MoonshotAI/kimi-agent-sdk"
+Documentation = "https://github.com/MoonshotAI/kimi-agent-sdk/tree/main/README.md"
+Changelog = "https://github.com/MoonshotAI/kimi-agent-sdk/blob/main/python/CHANGELOG.md"
+Issues = "https://github.com/MoonshotAI/kimi-agent-sdk/issues"
+
+[dependency-groups]
+dev = [
+    "inline-snapshot[black]>=0.31.1",
+    "pdoc>=16.0.0",
+    "pyright>=1.1.407",
+    "ty>=0.0.7",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.14.10",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = ["kimi_agent_sdk"]
+source-exclude = ["tests/**/*"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # Pyflakes
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "I",   # isort
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+include = [
+    "src/**/*.py",
+    "tests/**/*.py",
+]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[tool.ty.src]
+include = [
+    "src/**/*.py",
+    "tests/**/*.py",
+]

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/__init__.py

@@ -0,0 +1,195 @@
+"""
+Kimi Agent SDK is a Python SDK for building AI agents powered by Kimi.
+It provides both high-level and low-level APIs for seamless agent integration, stateful sessions,
+and tool orchestration in modern AI applications.
+
+Key features:
+
+- `kimi_agent_sdk.prompt` provides a high-level async generator API that sends prompts to Kimi
+  and yields aggregated Message objects, handling approval requests automatically or via custom
+  handlers.
+- `kimi_agent_sdk.Session` offers low-level control with Wire message access, manual approval
+  handling, session persistence, and context management for long-running agent interactions.
+- Message structures, approval types, and exceptions are re-exported from kosong and kimi_cli
+  for convenient access.
+
+Example (high-level API):
+
+```python
+import asyncio
+
+from kimi_agent_sdk import prompt
+
+
+async def main() -> None:
+    async for message in prompt(
+        "What is the capital of France?",
+        model="kimi",
+        yolo=True,
+    ):
+        print(message.extract_text())
+
+
+asyncio.run(main())
+```
+
+Example (low-level API with Session):
+
+```python
+import asyncio
+
+from kaos.path import KaosPath
+
+from kimi_agent_sdk import ApprovalRequest, Session
+
+
+async def main() -> None:
+    async with await Session.create(
+        work_dir=KaosPath.cwd(),
+        model="kimi",
+        yolo=False,
+    ) as session:
+        async for wire_msg in session.prompt("What is the capital of France?"):
+            if isinstance(wire_msg, ApprovalRequest):
+                wire_msg.resolve("approve")
+            else:
+                print(wire_msg)
+
+
+asyncio.run(main())
+```
+"""
+
+from __future__ import annotations
+
+from fastmcp.mcp_config import MCPConfig
+from kimi_cli.config import Config
+from kimi_cli.exception import (
+    AgentSpecError,
+    ConfigError,
+    InvalidToolError,
+    KimiCLIException,
+    MCPConfigError,
+    MCPRuntimeError,
+    SystemPromptTemplateError,
+)
+from kimi_cli.soul import LLMNotSet, LLMNotSupported, MaxStepsReached, RunCancelled
+from kimi_cli.wire.types import (
+    ApprovalRequest,
+    ApprovalResponse,
+    BriefDisplayBlock,
+    CompactionBegin,
+    CompactionEnd,
+    DiffDisplayBlock,
+    DisplayBlock,
+    Event,
+    Request,
+    ShellDisplayBlock,
+    StatusUpdate,
+    StepBegin,
+    StepInterrupted,
+    SubagentEvent,
+    TodoDisplayBlock,
+    TodoDisplayItem,
+    TokenUsage,
+    ToolCallPart,
+    ToolResult,
+    TurnBegin,
+    TurnEnd,
+    WireMessage,
+    is_event,
+    is_request,
+)
+from kosong.chat_provider import (
+    APIConnectionError,
+    APIEmptyResponseError,
+    APIStatusError,
+    APITimeoutError,
+    ChatProviderError,
+)
+from kosong.message import (
+    AudioURLPart,
+    ContentPart,
+    ImageURLPart,
+    Message,
+    TextPart,
+    ThinkPart,
+    ToolCall,
+    VideoURLPart,
+)
+from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
+
+from kimi_agent_sdk._approval import ApprovalHandlerFn
+from kimi_agent_sdk._exception import PromptValidationError, SessionStateError
+from kimi_agent_sdk._prompt import prompt
+from kimi_agent_sdk._session import Session
+
+__all__ = [
+    # Core API
+    "prompt",
+    "Session",
+    # Approval
+    "ApprovalHandlerFn",
+    "ApprovalRequest",
+    # High-level types
+    "Message",
+    "ContentPart",
+    "TextPart",
+    "ThinkPart",
+    "ImageURLPart",
+    "AudioURLPart",
+    "VideoURLPart",
+    "ToolCall",
+    # Low-level types (Wire)
+    "WireMessage",
+    "Event",
+    "Request",
+    "TurnBegin",
+    "TurnEnd",
+    "StepBegin",
+    "StepInterrupted",
+    "CompactionBegin",
+    "CompactionEnd",
+    "StatusUpdate",
+    "ToolCallPart",
+    "ToolResult",
+    "ToolReturnValue",
+    "ApprovalResponse",
+    "SubagentEvent",
+    "DisplayBlock",
+    "BriefDisplayBlock",
+    "DiffDisplayBlock",
+    "ShellDisplayBlock",
+    "TodoDisplayBlock",
+    "TodoDisplayItem",
+    "TokenUsage",
+    "is_event",
+    "is_request",
+    "CallableTool2",
+    "ToolOk",
+    "ToolError",
+    # Exceptions
+    "KimiAgentException",
+    "ConfigError",
+    "AgentSpecError",
+    "InvalidToolError",
+    "MCPConfigError",
+    "MCPRuntimeError",
+    "SystemPromptTemplateError",
+    "LLMNotSet",
+    "LLMNotSupported",
+    "ChatProviderError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "APIEmptyResponseError",
+    "MaxStepsReached",
+    "RunCancelled",
+    "PromptValidationError",
+    "SessionStateError",
+    # Others
+    "Config",
+    "MCPConfig",
+]
+
+type KimiAgentException = KimiCLIException

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/_aggregator.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kimi_cli.soul.message import tool_result_to_message
+from kimi_cli.wire.types import StepBegin, StepInterrupted, ToolCallPart, ToolResult, WireMessage
+from kosong.message import ContentPart, Message, ToolCall
+
+
+def _merge_content(buffer: list[ContentPart], part: ContentPart) -> None:
+    if not buffer or not buffer[-1].merge_in_place(part):
+        buffer.append(part)
+
+
+class MessageAggregator:
+    """
+    Aggregate WireMessage stream into Message stream.
+
+    - final_message_only=False: like JsonPrinter, outputs per step and tool results
+    - final_message_only=True: like FinalOnlyJsonPrinter, outputs only the last step text
+    """
+
+    @dataclass(slots=True)
+    class _ToolCallState:
+        tool_call: ToolCall
+        tool_result: ToolResult | None
+
+    def __init__(self, final_message_only: bool = False) -> None:
+        self._final_message_only = final_message_only
+        self._content_buffer: list[ContentPart] = []
+        self._tool_call_buffer: dict[str, MessageAggregator._ToolCallState] = {}
+        self._last_tool_call: ToolCall | None = None
+
+    def feed(self, msg: WireMessage) -> list[Message]:
+        match msg:
+            case StepBegin() | StepInterrupted():
+                if self._final_message_only:
+                    self._reset_buffers()
+                    return []
+                return self._flush()
+            case ContentPart() as part:
+                _merge_content(self._content_buffer, part)
+            case ToolCall() as call:
+                if self._final_message_only:
+                    return []
+                self._tool_call_buffer[call.id] = MessageAggregator._ToolCallState(
+                    tool_call=call, tool_result=None
+                )
+                self._last_tool_call = call
+            case ToolCallPart() as part:
+                if self._final_message_only:
+                    return []
+                if self._last_tool_call is None:
+                    return []
+                self._last_tool_call.merge_in_place(part)
+            case ToolResult() as result:
+                if self._final_message_only:
+                    return []
+                state = self._tool_call_buffer.get(result.tool_call_id)
+                if state is None:
+                    return []
+                state.tool_result = result
+            case _:
+                pass
+        return []
+
+    def flush(self) -> list[Message]:
+        return self._flush()
+
+    def _flush(self) -> list[Message]:
+        if self._final_message_only:
+            return self._flush_final_only()
+        return self._flush_full()
+
+    def _flush_final_only(self) -> list[Message]:
+        if not self._content_buffer:
+            return []
+        message = Message(role="assistant", content=self._content_buffer)
+        text = message.extract_text()
+        self._reset_buffers()
+        if not text:
+            return []
+        return [Message(role="assistant", content=text)]
+
+    def _flush_full(self) -> list[Message]:
+        if not self._content_buffer and not self._tool_call_buffer:
+            return []
+
+        tool_calls: list[ToolCall] = []
+        tool_results: list[ToolResult] = []
+        for state in self._tool_call_buffer.values():
+            if state.tool_result is None:
+                continue
+            tool_calls.append(state.tool_call)
+            tool_results.append(state.tool_result)
+
+        messages: list[Message] = [
+            Message(
+                role="assistant",
+                content=self._content_buffer,
+                tool_calls=tool_calls or None,
+            )
+        ]
+        for result in tool_results:
+            messages.append(tool_result_to_message(result))
+
+        self._reset_buffers()
+        return messages
+
+    def _reset_buffers(self) -> None:
+        self._content_buffer.clear()
+        self._tool_call_buffer.clear()
+        self._last_tool_call = None

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/_approval.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from kimi_cli.wire.types import ApprovalRequest
+
+type ApprovalHandlerFn = (
+    Callable[[ApprovalRequest], None] | Callable[[ApprovalRequest], Awaitable[None]]
+)
+"""
+Approval handler callback function type.
+
+The callback receives an ApprovalRequest with the following attributes and is responsible
+for calling request.resolve(...):
+    - id: Unique request identifier
+    - tool_call_id: Associated tool call ID
+    - sender: Name of the tool that initiated the request
+    - action: Action type
+    - description: Detailed description
+    - display: List of visualization info
+
+Resolve with:
+    - "approve": Approve this request
+    - "approve_for_session": Approve and auto-approve subsequent similar requests
+    - "reject": Reject the request
+"""

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/_exception.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from kimi_cli.exception import KimiCLIException
+
+
+class PromptValidationError(KimiCLIException, ValueError):
+    """Invalid prompt configuration."""
+
+    pass
+
+
+class SessionStateError(KimiCLIException, RuntimeError):
+    """Invalid session state for prompt execution."""
+
+    pass

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/_prompt.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from kaos.path import KaosPath
+from kimi_cli.config import Config
+from kimi_cli.wire.types import ApprovalRequest
+from kosong.message import ContentPart, Message
+
+from kimi_agent_sdk._aggregator import MessageAggregator
+from kimi_agent_sdk._approval import ApprovalHandlerFn
+from kimi_agent_sdk._exception import PromptValidationError
+from kimi_agent_sdk._session import Session
+
+if TYPE_CHECKING:
+    from fastmcp.mcp_config import MCPConfig
+
+
+async def prompt(
+    user_input: str | list[ContentPart],
+    *,
+    # Basic configuration
+    work_dir: KaosPath | None = None,
+    config: Config | Path | None = None,
+    model: str | None = None,
+    thinking: bool = False,
+    # Run mode
+    yolo: bool = False,
+    approval_handler_fn: ApprovalHandlerFn | None = None,
+    # Extensions
+    agent_file: Path | None = None,
+    mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
+    skills_dir: KaosPath | None = None,
+    # Loop control
+    max_steps_per_turn: int | None = None,
+    max_retries_per_step: int | None = None,
+    max_ralph_iterations: int | None = None,
+    # Output control
+    final_message_only: bool = False,
+) -> AsyncGenerator[Message, None]:
+    """
+    Send a prompt to the Kimi Agent and get streaming responses.
+
+    This is the highest-level API that aggregates Wire messages into Message objects,
+    similar to `kimi --print --output stream-json`.
+
+    Args:
+        user_input: User input, can be plain text or a list of content parts.
+        work_dir: Working directory (KaosPath). Defaults to current directory.
+        config: Configuration object or path to a config file.
+        model: Model name, e.g. "kimi".
+        thinking: Whether to enable thinking mode (requires model support).
+        yolo: Automatically approve all approval requests.
+        approval_handler_fn: Custom approval handler callback (sync or async).
+        agent_file: Agent specification file path.
+        mcp_configs: MCP server configurations.
+        skills_dir: Skills directory (KaosPath).
+        max_steps_per_turn: Maximum number of steps in one turn.
+        max_retries_per_step: Maximum number of retries per step.
+        max_ralph_iterations: Extra iterations in Ralph mode (-1 for unlimited).
+        final_message_only: Only return the final Message of the last step.
+
+    Yields:
+        Message: Aggregated assistant/tool messages.
+
+    Raises:
+        LLMNotSet: When the LLM is not set.
+        LLMNotSupported: When the LLM does not have required capabilities.
+        ChatProviderError: When the LLM provider returns an error.
+        MaxStepsReached: When the maximum number of steps is reached.
+        RunCancelled: When the run is cancelled by the cancel event.
+        PromptValidationError: When neither of yolo/approval_handler_fn are provided.
+
+    Note:
+        If yolo=True and approval_handler_fn is provided, the handler is ignored.
+    """
+
+    if not yolo and approval_handler_fn is None:
+        raise PromptValidationError("Either yolo=True or approval_handler_fn must be provided")
+
+    def _auto_approve(request: ApprovalRequest) -> None:
+        request.resolve("approve")
+
+    if yolo:
+        approval_handler: ApprovalHandlerFn = _auto_approve
+    else:
+        assert approval_handler_fn is not None
+        approval_handler = approval_handler_fn
+
+    async with await Session.create(
+        work_dir=work_dir,
+        config=config,
+        model=model,
+        thinking=thinking,
+        yolo=yolo,
+        agent_file=agent_file,
+        mcp_configs=mcp_configs,
+        skills_dir=skills_dir,
+        max_steps_per_turn=max_steps_per_turn,
+        max_retries_per_step=max_retries_per_step,
+        max_ralph_iterations=max_ralph_iterations,
+    ) as session:
+        aggregator = MessageAggregator(final_message_only=final_message_only)
+        async for wire_msg in session.prompt(user_input, merge_wire_messages=True):
+            if isinstance(wire_msg, ApprovalRequest):
+                result = approval_handler(wire_msg)
+                if inspect.isawaitable(result):
+                    await result
+                if not wire_msg.resolved:
+                    wire_msg.resolve("reject")
+                continue
+
+            for message in aggregator.feed(wire_msg):
+                yield message
+
+        for message in aggregator.flush():
+            yield message

kimi_agent_sdk_x-0.0.5/src/kimi_agent_sdk/_session.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from kaos.path import KaosPath
+from kimi_cli.app import KimiCLI
+from kimi_cli.config import Config
+from kimi_cli.session import Session as CliSession
+from kimi_cli.soul import StatusSnapshot
+from kimi_cli.wire.types import ContentPart, WireMessage
+from kimi_cli.soul.agent import BuiltinSystemPromptArgs
+
+from kimi_agent_sdk._exception import SessionStateError
+
+if TYPE_CHECKING:
+    from kimi_agent_sdk import MCPConfig
+
+
+def _ensure_type(name: str, value: object, expected: type) -> None:
+    if not isinstance(value, expected):
+        raise TypeError(f"{name} must be {expected.__name__}, got {type(value).__name__}")
+
+def _ensure_skill_dirs(skill_dirs: object) -> list[KaosPath]:
+    from collections.abc import Iterable
+    if skill_dirs is None:
+        return []
+    if type(skill_dirs) == list:
+        return skill_dirs
+    if isinstance(skill_dirs, Iterable) and not isinstance(skill_dirs, (str, bytes)):
+        return [i for i in skill_dirs]
+    return [skill_dirs]
+
+class Session:
+    """
+    Kimi Agent session with low-level control.
+
+    Use this class when you need full access to Wire messages, manual approval
+    handling, or session persistence across prompts.
+    """
+
+    def __init__(self, cli: KimiCLI) -> None:
+        self._cli = cli
+        self._cancel_event: asyncio.Event | None = None
+        self._closed = False
+
+    @staticmethod
+    async def create(
+        work_dir: KaosPath | None = None,
+        *,
+        # Basic configuration
+        session_id: str | None = None,
+        config: Config | Path | None = None,
+        model: str | None = None,
+        thinking: bool = False,
+        # Run mode
+        yolo: bool = False,
+        plan_mode: bool = False,
+        # Extensions
+        agent_file: Path | None = None,
+        mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
+        skills_dirs: list[KaosPath] | KaosPath | None = None,
+        # Loop control
+        max_steps_per_turn: int | None = None,
+        max_retries_per_step: int | None = None,
+        max_ralph_iterations: int | None = None,
+        tool_call_failed_list: list[tuple[str, str, str, str]]  | None = None, # Add by maxwell
+        custom_system_prompt : Callable[[BuiltinSystemPromptArgs], str] | None = None, # Add by maxwell
+    ) -> Session:
+        """
+        Create a new Session instance.
+
+        Args:
+            work_dir: Working directory (KaosPath). Defaults to current directory.
+            session_id: Custom session ID (optional).
+            config: Configuration object or path to a config file.
+            model: Model name, e.g. "kimi".
+            thinking: Whether to enable thinking mode (requires model support).
+            yolo: Automatically approve all approval requests.
+            agent_file: Agent specification file path.
+            mcp_configs: MCP server configurations.
+            skills_dirs: Skills directories (KaosPath or list of KaosPath).
+            max_steps_per_turn: Maximum number of steps in one turn.
+            max_retries_per_step: Maximum number of retries per step.
+            max_ralph_iterations: Extra iterations in Ralph mode (-1 for unlimited).
+
+        Returns:
+            Session: A new Session instance.
+
+        Raises:
+            FileNotFoundError: When the agent file is not found.
+            ConfigError(KimiCLIException, ValueError): When the configuration is invalid.
+            AgentSpecError(KimiCLIException, ValueError): When the agent specification is invalid.
+            InvalidToolError(KimiCLIException, ValueError): When any tool cannot be loaded.
+            MCPConfigError(KimiCLIException, ValueError): When any MCP configuration is invalid.
+            MCPRuntimeError(KimiCLIException, RuntimeError): When any MCP server cannot be
+                connected.
+        """
+        if work_dir is None:
+            work_dir_path = KaosPath.cwd()
+        else:
+            _ensure_type("work_dir", work_dir, KaosPath)
+            work_dir_path = work_dir
+        skill_dirs_list = _ensure_skill_dirs(skills_dirs)
+        for i, sd in enumerate(skill_dirs_list):
+            _ensure_type(f"skills_dirs[{i}]", sd, KaosPath)
+        cli_session = await CliSession.create(work_dir_path, session_id)
+        cli = await KimiCLI.create(
+            cli_session,
+            config=config,
+            model_name=model,
+            thinking=thinking,
+            yolo=yolo,
+            plan_mode=plan_mode,
+            agent_file=agent_file,
+            mcp_configs=mcp_configs,
+            skills_dirs=skill_dirs_list,
+            max_steps_per_turn=max_steps_per_turn,
+            max_retries_per_step=max_retries_per_step,
+            max_ralph_iterations=max_ralph_iterations,
+            tool_call_failed_list=tool_call_failed_list,
+            custom_system_prompt=custom_system_prompt,
+        )
+        return Session(cli)
+
+    @staticmethod
+    async def resume(
+        work_dir: KaosPath,
+        session_id: str | None = None,
+        *,
+        # Basic configuration
+        config: Config | Path | None = None,
+        model: str | None = None,
+        thinking: bool = False,
+        # Run mode
+        yolo: bool = False,
+        plan_mode: bool = False,
+        # Extensions
+        agent_file: Path | None = None,
+        mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
+        skills_dirs: list[KaosPath] | KaosPath | None = None,
+        # Loop control
+        max_steps_per_turn: int | None = None,
+        max_retries_per_step: int | None = None,
+        max_ralph_iterations: int | None = None,
+        tool_call_failed_list: list[tuple[str, str, str, str]]  | None = None, # Add by maxwell
+        custom_system_prompt : Callable[[BuiltinSystemPromptArgs], str] | None = None, # Add by maxwell
+    ) -> Session | None:
+        """
+        Resume an existing session.
+
+        Args:
+            work_dir: Working directory to resume from (KaosPath).
+            session_id: Session ID to resume. If None, resumes the most recent session.
+            config: Configuration object or path to a config file.
+            model: Model name, e.g. "kimi".
+            thinking: Whether to enable thinking mode (requires model support).
+            yolo: Automatically approve all approval requests.
+            agent_file: Agent specification file path.
+            mcp_configs: MCP server configurations.
+            skills_dirs: Skills directories (KaosPath or list of KaosPath).
+            max_steps_per_turn: Maximum number of steps in one turn.
+            max_retries_per_step: Maximum number of retries per step.
+            max_ralph_iterations: Extra iterations in Ralph mode (-1 for unlimited).
+
+        Returns:
+            Session | None: The resumed session, or None if not found.
+
+        Raises:
+            FileNotFoundError: When the agent file is not found.
+            ConfigError(KimiCLIException, ValueError): When the configuration is invalid.
+            AgentSpecError(KimiCLIException, ValueError): When the agent specification is invalid.
+            InvalidToolError(KimiCLIException, ValueError): When any tool cannot be loaded.
+            MCPConfigError(KimiCLIException, ValueError): When any MCP configuration is invalid.
+            MCPRuntimeError(KimiCLIException, RuntimeError): When any MCP server cannot be
+                connected.
+        """
+        _ensure_type("work_dir", work_dir, KaosPath)
+        skill_dirs_list = _ensure_skill_dirs(skills_dirs)
+        for i, sd in enumerate(skill_dirs_list):
+            _ensure_type(f"skills_dirs[{i}]", sd, KaosPath)
+        if session_id is None:
+            cli_session = await CliSession.continue_(work_dir)
+        else:
+            cli_session = await CliSession.find(work_dir, session_id)
+        if cli_session is None:
+            return None
+        cli = await KimiCLI.create(
+            cli_session,
+            config=config,
+            model_name=model,
+            thinking=thinking,
+            yolo=yolo,
+            plan_mode=plan_mode,
+            agent_file=agent_file,
+            mcp_configs=mcp_configs,
+            skills_dirs=skill_dirs_list,
+            max_steps_per_turn=max_steps_per_turn,
+            max_retries_per_step=max_retries_per_step,
+            max_ralph_iterations=max_ralph_iterations,
+            tool_call_failed_list=tool_call_failed_list,
+            custom_system_prompt=custom_system_prompt,
+        )
+        return Session(cli)
+
+    @property
+    def id(self) -> str:
+        """Session ID."""
+        return self._cli.session.id
+
+    @property
+    def model_name(self) -> str:
+        """Name of the current model."""
+        return self._cli.soul.model_name
+
+    @property
+    def status(self) -> StatusSnapshot:
+        """Current status snapshot (context usage, yolo state, etc.)."""
+        return self._cli.soul.status
+
+    async def prompt(
+        self,
+        user_input: str | list[ContentPart],
+        *,
+        merge_wire_messages: bool = False,
+    ) -> AsyncGenerator[WireMessage, None]:
+        """
+        Send a prompt and get a WireMessage stream.
+
+        Args:
+            user_input: User input, can be plain text or a list of content parts.
+            merge_wire_messages: Whether to merge consecutive Wire messages.
+
+        Yields:
+            WireMessage: Wire messages, including ApprovalRequest.
+
+        Raises:
+            LLMNotSet: When the LLM is not set.
+            LLMNotSupported: When the LLM does not have required capabilities.
+            ChatProviderError: When the LLM provider returns an error.
+            MaxStepsReached: When the maximum number of steps is reached.
+            RunCancelled: When the run is cancelled by the cancel event.
+            SessionStateError: When the session is closed or already running.
+
+        Note:
+            Callers must handle ApprovalRequest manually unless yolo=True.
+        """
+        if self._closed:
+            raise SessionStateError("Session is closed")
+        if self._cancel_event is not None:
+            raise SessionStateError("Session is already running")
+        cancel_event = asyncio.Event()
+        self._cancel_event = cancel_event
+        try:
+            async for msg in self._cli.run(
+                user_input,
+                cancel_event,
+                merge_wire_messages=merge_wire_messages,
+            ):
+                yield msg
+        finally:
+            if self._cancel_event is cancel_event:
+                self._cancel_event = None
+
+    def cancel(self) -> None:
+        """
+        Cancel the current prompt operation.
+
+        This sets the cancel event used by the underlying KimiCLI.run call and
+        results in RunCancelled being raised from the active prompt coroutine.
+        """
+        if self._cancel_event is not None:
+            self._cancel_event.set()
+
+    async def close(self) -> None:
+        """
+        Close the Session and release resources.
+
+        This cancels any ongoing prompt and cleans up tool resources.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        if self._cancel_event is not None:
+            self._cancel_event.set()
+        toolset = getattr(self._cli.soul.agent, "toolset", None)
+        cleanup = getattr(toolset, "cleanup", None)
+        if cleanup is None:
+            return
+        result = cleanup()
+        if inspect.isawaitable(result):
+            await result
+
+    async def __aenter__(self) -> Session:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Async context manager exit."""
+        await self.close()