Align Python SDK path types with Kimi CLI signatures (#13)

* fix: unify work_dir and skills_dir types to KaosPath in session and prompt APIs

* test: add tests for Session and prompt requiring KaosPath for work_dir and skills_dir

* fix: update kimi-cli dependency version to 0.79

Author: RealKai42

python/README.md

@@ -34,11 +34,12 @@ asyncio.run(main())
 
 ```python
 import asyncio
+from kaos.path import KaosPath
 from kimi_agent_sdk import ApprovalRequest, Session, TextPart
 
 
 async def main() -> None:
-    async with await Session.create(work_dir=".") as session:
+    async with await Session.create(work_dir=KaosPath.cwd()) as session:
         async for wire_msg in session.prompt("List files in current directory"):
             match wire_msg:
                 case TextPart(text=text):
@@ -54,4 +55,5 @@ asyncio.run(main())
 
 - `prompt()` creates a temporary session per call.
 - `Session.prompt()` yields raw Wire messages and requires handling approvals.
+- `work_dir` and `skills_dir` expect `KaosPath` values.
 - See the API docstrings for more configuration options.

python/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dependencies = [
-    "kimi-cli>=0.77,<0.78",
+    "kimi-cli>=0.79,<0.80",
     "kosong>=0.38.0,<0.39.0",
 ]
 

python/src/kimi_agent_sdk/_prompt.py

@@ -5,6 +5,7 @@
 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
@@ -22,7 +23,7 @@ async def prompt(
     user_input: str | list[ContentPart],
     *,
     # Basic configuration
-    work_dir: Path | str | None = None,
+    work_dir: KaosPath | None = None,
     config: Config | Path | None = None,
     model: str | None = None,
     thinking: bool = False,
@@ -32,7 +33,7 @@ async def prompt(
     # Extensions
     agent_file: Path | None = None,
     mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
-    skills_dir: Path | None = None,
+    skills_dir: KaosPath | None = None,
     # Loop control
     max_steps_per_turn: int | None = None,
     max_retries_per_step: int | None = None,
@@ -48,15 +49,15 @@ async def prompt(
 
     Args:
         user_input: User input, can be plain text or a list of content parts.
-        work_dir: Working directory. Defaults to current directory.
+        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.
+        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).

python/src/kimi_agent_sdk/_session.py

@@ -19,14 +19,9 @@
     from kimi_agent_sdk import MCPConfig
 
 
-def _coerce_work_dir(work_dir: Path | str | None) -> KaosPath:
-    if work_dir is None:
-        return KaosPath.cwd()
-    if isinstance(work_dir, KaosPath):
-        return work_dir.expanduser()
-    if isinstance(work_dir, Path):
-        return KaosPath.unsafe_from_local_path(work_dir).expanduser()
-    return KaosPath(str(work_dir)).expanduser()
+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__}")
 
 
 class Session:
@@ -44,7 +39,7 @@ def __init__(self, cli: KimiCLI) -> None:
 
     @staticmethod
     async def create(
-        work_dir: Path | str | None = None,
+        work_dir: KaosPath | None = None,
         *,
         # Basic configuration
         session_id: str | None = None,
@@ -56,7 +51,7 @@ async def create(
         # Extensions
         agent_file: Path | None = None,
         mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
-        skills_dir: Path | None = None,
+        skills_dir: KaosPath | None = None,
         # Loop control
         max_steps_per_turn: int | None = None,
         max_retries_per_step: int | None = None,
@@ -66,15 +61,15 @@ async def create(
         Create a new Session instance.
 
         Args:
-            work_dir: Working directory. Defaults to current directory.
+            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_dir: Skills directory.
+            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).
@@ -91,7 +86,14 @@ async def create(
             MCPRuntimeError(KimiCLIException, RuntimeError): When any MCP server cannot be
                 connected.
         """
-        work_dir_path = _coerce_work_dir(work_dir)
+        if work_dir is None:
+            work_dir_path = KaosPath.cwd()
+        else:
+            _ensure_type("work_dir", work_dir, KaosPath)
+            work_dir_path = work_dir
+
+        if skills_dir is not None:
+            _ensure_type("skills_dir", skills_dir, KaosPath)
         cli_session = await CliSession.create(work_dir_path, session_id)
         cli = await KimiCLI.create(
             cli_session,
@@ -110,7 +112,7 @@ async def create(
 
     @staticmethod
     async def resume(
-        work_dir: Path | str,
+        work_dir: KaosPath,
         session_id: str | None = None,
         *,
         # Basic configuration
@@ -122,7 +124,7 @@ async def resume(
         # Extensions
         agent_file: Path | None = None,
         mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
-        skills_dir: Path | None = None,
+        skills_dir: KaosPath | None = None,
         # Loop control
         max_steps_per_turn: int | None = None,
         max_retries_per_step: int | None = None,
@@ -132,15 +134,15 @@ async def resume(
         Resume an existing session.
 
         Args:
-            work_dir: Working directory to resume from.
+            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_dir: Skills directory.
+            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).
@@ -157,11 +159,13 @@ async def resume(
             MCPRuntimeError(KimiCLIException, RuntimeError): When any MCP server cannot be
                 connected.
         """
-        work_dir_path = _coerce_work_dir(work_dir)
+        _ensure_type("work_dir", work_dir, KaosPath)
+        if skills_dir is not None:
+            _ensure_type("skills_dir", skills_dir, KaosPath)
         if session_id is None:
-            cli_session = await CliSession.continue_(work_dir_path)
+            cli_session = await CliSession.continue_(work_dir)
         else:
-            cli_session = await CliSession.find(work_dir_path, session_id)
+            cli_session = await CliSession.find(work_dir, session_id)
         if cli_session is None:
             return None
         cli = await KimiCLI.create(

python/tests/test_paths.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+from kaos.path import KaosPath
+
+from kimi_agent_sdk import Session, prompt
+from kimi_agent_sdk import _session as session_module
+
+
+@pytest.mark.asyncio
+async def test_session_create_requires_kaos_work_dir() -> None:
+    with pytest.raises(TypeError, match="work_dir must be KaosPath"):
+        await Session.create(work_dir=cast(Any, Path(".")))
+
+
+@pytest.mark.asyncio
+async def test_session_resume_requires_kaos_work_dir() -> None:
+    with pytest.raises(TypeError, match="work_dir must be KaosPath"):
+        await Session.resume(cast(Any, Path(".")))
+
+
+@pytest.mark.asyncio
+async def test_session_create_requires_kaos_skills_dir() -> None:
+    with pytest.raises(TypeError, match="skills_dir must be KaosPath"):
+        await Session.create(work_dir=KaosPath.cwd(), skills_dir=cast(Any, Path(".")))
+
+
+@pytest.mark.asyncio
+async def test_prompt_requires_kaos_work_dir() -> None:
+    with pytest.raises(TypeError, match="work_dir must be KaosPath"):
+        await anext(prompt("hi", yolo=True, work_dir=cast(Any, Path("."))))
+
+
+@pytest.mark.asyncio
+async def test_prompt_requires_kaos_skills_dir() -> None:
+    with pytest.raises(TypeError, match="skills_dir must be KaosPath"):
+        await anext(prompt("hi", yolo=True, skills_dir=cast(Any, Path("."))))
+
+
+@pytest.mark.asyncio
+async def test_session_create_accepts_kaos_paths(monkeypatch: pytest.MonkeyPatch) -> None:
+    async def _dummy_session_create(*_args: Any, **_kwargs: Any) -> Any:
+        return object()
+
+    async def _dummy_cli_create(*_args: Any, **_kwargs: Any) -> Any:
+        return cast(Any, object())
+
+    monkeypatch.setattr(session_module.CliSession, "create", _dummy_session_create)
+    monkeypatch.setattr(session_module.KimiCLI, "create", _dummy_cli_create)
+
+    session = await Session.create(work_dir=KaosPath.cwd(), skills_dir=KaosPath.cwd())
+    assert isinstance(session, Session)