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

kimi_cli/session.py

@@ -1,65 +1,251 @@
+from __future__ import annotations
+
+import asyncio
+import builtins
+import shutil
 import uuid
+from dataclasses import dataclass
 from pathlib import Path
-from typing import NamedTuple
+from textwrap import shorten
+
+import aiofiles
+from kaos.path import KaosPath
+from kosong.message import Message
 
 from kimi_cli.metadata import WorkDirMeta, load_metadata, save_metadata
 from kimi_cli.utils.logging import logger
+from kimi_cli.wire.serde import WireMessageRecord
+from kimi_cli.wire.types import TurnBegin
 
 
-class Session(NamedTuple):
+@dataclass(slots=True, kw_only=True)
+class Session:
     """A session of a work directory."""
 
+    # static metadata
     id: str
-    work_dir: Path
-    history_file: Path
+    """The session ID."""
+    work_dir: KaosPath
+    """The absolute path of the work directory."""
+    work_dir_meta: WorkDirMeta
+    """The metadata of the work directory."""
+    context_file: Path
+    """The absolute path to the file storing the message history."""
+
+    # refreshable metadata
+    title: str
+    """The title of the session."""
+    updated_at: float
+    """The timestamp of the last update to the session."""
+
+    @property
+    def dir(self) -> Path:
+        """The absolute path of the session directory."""
+        path = self.work_dir_meta.sessions_dir / self.id
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def wire_file(self) -> Path:
+        """The file backend for persisting Wire messages."""
+        return self.dir / "wire.jsonl"
+
+    def is_empty(self) -> bool:
+        """Whether the session has any context history."""
+        try:
+            return self.context_file.stat().st_size == 0
+        except FileNotFoundError:
+            return True
+
+    async def delete(self) -> None:
+        """Delete the session directory."""
+        session_dir = self.work_dir_meta.sessions_dir / self.id
+        if not session_dir.exists():
+            return
+        await asyncio.to_thread(shutil.rmtree, session_dir, True)
+
+    async def refresh(self) -> None:
+        self.title = f"Untitled ({self.id})"
+        self.updated_at = self.context_file.stat().st_mtime if self.context_file.exists() else 0.0
+
+        if not self.wire_file.exists():
+            return
+
+        try:
+            async with aiofiles.open(self.wire_file, encoding="utf-8") as f:
+                async for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        record = WireMessageRecord.model_validate_json(line)
+                        wire_msg = record.to_wire_message()
+                    except Exception:
+                        logger.exception(
+                            "Failed to parse line in wire file {file}:", file=self.wire_file
+                        )
+                        continue
+                    if isinstance(wire_msg, TurnBegin):
+                        title = shorten(
+                            Message(role="user", content=wire_msg.user_input).extract_text(" "),
+                            width=50,
+                        )
+                        self.title = f"{title} ({self.id})"
+                        return
+        except Exception:
+            logger.exception(
+                "Failed to derive session title from wire file {file}:", file=self.wire_file
+            )
 
     @staticmethod
-    def create(work_dir: Path, _history_file: Path | None = None) -> "Session":
+    async def create(
+        work_dir: KaosPath,
+        session_id: str | None = None,
+        _context_file: Path | None = None,
+    ) -> Session:
         """Create a new session for a work directory."""
+        work_dir = work_dir.canonical()
         logger.debug("Creating new session for work directory: {work_dir}", work_dir=work_dir)
 
         metadata = load_metadata()
-        work_dir_meta = next((wd for wd in metadata.work_dirs if wd.path == str(work_dir)), None)
+        work_dir_meta = metadata.get_work_dir_meta(work_dir)
         if work_dir_meta is None:
-            work_dir_meta = WorkDirMeta(path=str(work_dir))
-            metadata.work_dirs.append(work_dir_meta)
+            work_dir_meta = metadata.new_work_dir_meta(work_dir)
 
-        session_id = str(uuid.uuid4())
-        if _history_file is None:
-            history_file = work_dir_meta.sessions_dir / f"{session_id}.jsonl"
-            work_dir_meta.last_session_id = session_id
+        if session_id is None:
+            session_id = str(uuid.uuid4())
+        session_dir = work_dir_meta.sessions_dir / session_id
+        session_dir.mkdir(parents=True, exist_ok=True)
+
+        if _context_file is None:
+            context_file = session_dir / "context.jsonl"
         else:
             logger.warning(
-                "Using provided history file: {history_file}", history_file=_history_file
+                "Using provided context file: {context_file}", context_file=_context_file
             )
-            _history_file.parent.mkdir(parents=True, exist_ok=True)
-            if _history_file.exists():
-                assert _history_file.is_file()
-            history_file = _history_file
+            _context_file.parent.mkdir(parents=True, exist_ok=True)
+            if _context_file.exists():
+                assert _context_file.is_file()
+            context_file = _context_file
 
-        if history_file.exists():
+        if context_file.exists():
             # truncate if exists
             logger.warning(
-                "History file already exists, truncating: {history_file}", history_file=history_file
+                "Context file already exists, truncating: {context_file}", context_file=context_file
             )
-            history_file.unlink()
-            history_file.touch()
+            context_file.unlink()
+        context_file.touch()
 
         save_metadata(metadata)
 
-        return Session(
+        session = Session(
+            id=session_id,
+            work_dir=work_dir,
+            work_dir_meta=work_dir_meta,
+            context_file=context_file,
+            title="",
+            updated_at=0.0,
+        )
+        await session.refresh()
+        return session
+
+    @staticmethod
+    async def find(work_dir: KaosPath, session_id: str) -> Session | None:
+        """Find a session by work directory and session ID."""
+        work_dir = work_dir.canonical()
+        logger.debug(
+            "Finding session for work directory: {work_dir}, session ID: {session_id}",
+            work_dir=work_dir,
+            session_id=session_id,
+        )
+
+        metadata = load_metadata()
+        work_dir_meta = metadata.get_work_dir_meta(work_dir)
+        if work_dir_meta is None:
+            logger.debug("Work directory never been used")
+            return None
+
+        _migrate_session_context_file(work_dir_meta, session_id)
+
+        session_dir = work_dir_meta.sessions_dir / session_id
+        if not session_dir.is_dir():
+            logger.debug("Session directory not found: {session_dir}", session_dir=session_dir)
+            return None
+
+        context_file = session_dir / "context.jsonl"
+        if not context_file.exists():
+            logger.debug(
+                "Session context file not found: {context_file}", context_file=context_file
+            )
+            return None
+
+        session = Session(
             id=session_id,
             work_dir=work_dir,
-            history_file=history_file,
+            work_dir_meta=work_dir_meta,
+            context_file=context_file,
+            title="",
+            updated_at=0.0,
         )
+        await session.refresh()
+        return session
+
+    @staticmethod
+    async def list(work_dir: KaosPath) -> builtins.list[Session]:
+        """List all sessions for a work directory."""
+        work_dir = work_dir.canonical()
+        logger.debug("Listing sessions for work directory: {work_dir}", work_dir=work_dir)
+
+        metadata = load_metadata()
+        work_dir_meta = metadata.get_work_dir_meta(work_dir)
+        if work_dir_meta is None:
+            logger.debug("Work directory never been used")
+            return []
+
+        session_ids = {
+            path.name if path.is_dir() else path.stem
+            for path in work_dir_meta.sessions_dir.iterdir()
+            if path.is_dir() or path.suffix == ".jsonl"
+        }
+
+        sessions: list[Session] = []
+        for session_id in session_ids:
+            _migrate_session_context_file(work_dir_meta, session_id)
+            session_dir = work_dir_meta.sessions_dir / session_id
+            if not session_dir.is_dir():
+                logger.debug("Session directory not found: {session_dir}", session_dir=session_dir)
+                continue
+            context_file = session_dir / "context.jsonl"
+            if not context_file.exists():
+                logger.debug(
+                    "Session context file not found: {context_file}", context_file=context_file
+                )
+                continue
+            session = Session(
+                id=session_id,
+                work_dir=work_dir,
+                work_dir_meta=work_dir_meta,
+                context_file=context_file,
+                title="",
+                updated_at=0.0,
+            )
+            if session.is_empty():
+                logger.debug(
+                    "Session context file is empty: {context_file}", context_file=context_file
+                )
+                continue
+            await session.refresh()
+            sessions.append(session)
+        sessions.sort(key=lambda session: session.updated_at, reverse=True)
+        return sessions
 
     @staticmethod
-    def continue_(work_dir: Path) -> "Session | None":
+    async def continue_(work_dir: KaosPath) -> Session | None:
         """Get the last session for a work directory."""
+        work_dir = work_dir.canonical()
         logger.debug("Continuing session for work directory: {work_dir}", work_dir=work_dir)
 
         metadata = load_metadata()
-        work_dir_meta = next((wd for wd in metadata.work_dirs if wd.path == str(work_dir)), None)
+        work_dir_meta = metadata.get_work_dir_meta(work_dir)
         if work_dir_meta is None:
             logger.debug("Work directory never been used")
             return None
@@ -71,11 +257,17 @@ class Session(NamedTuple):
             "Found last session for work directory: {session_id}",
             session_id=work_dir_meta.last_session_id,
         )
-        session_id = work_dir_meta.last_session_id
-        history_file = work_dir_meta.sessions_dir / f"{session_id}.jsonl"
+        return await Session.find(work_dir, work_dir_meta.last_session_id)
 
-        return Session(
-            id=session_id,
-            work_dir=work_dir,
-            history_file=history_file,
+
+def _migrate_session_context_file(work_dir_meta: WorkDirMeta, session_id: str) -> None:
+    old_context_file = work_dir_meta.sessions_dir / f"{session_id}.jsonl"
+    new_context_file = work_dir_meta.sessions_dir / session_id / "context.jsonl"
+    if old_context_file.exists() and not new_context_file.exists():
+        new_context_file.parent.mkdir(parents=True, exist_ok=True)
+        old_context_file.rename(new_context_file)
+        logger.info(
+            "Migrated session context file from {old} to {new}",
+            old=old_context_file,
+            new=new_context_file,
         )

kimi_cli/share.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pathlib import Path
 
 

kimi_cli/skill.py

@@ -0,0 +1,145 @@
+"""Skill specification discovery and loading utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from loguru import logger
+from pydantic import BaseModel, ConfigDict
+
+from kimi_cli.share import get_share_dir
+from kimi_cli.utils.frontmatter import read_frontmatter
+
+
+def get_skills_dir() -> Path:
+    """
+    Get the default skills directory path.
+    """
+    return get_share_dir() / "skills"
+
+
+def get_builtin_skills_dir() -> Path:
+    """
+    Get the built-in skills directory path.
+    """
+    return Path(__file__).parent / "skills"
+
+
+def get_claude_skills_dir() -> Path:
+    """
+    Get the default skills directory path of Claude.
+    """
+    return Path.home() / ".claude" / "skills"
+
+
+def normalize_skill_name(name: str) -> str:
+    """Normalize a skill name for lookup."""
+    return name.casefold()
+
+
+def index_skills(skills: Iterable[Skill]) -> dict[str, Skill]:
+    """Build a lookup table for skills by normalized name."""
+    return {normalize_skill_name(skill.name): skill for skill in skills}
+
+
+def discover_skills_from_roots(skills_dirs: Iterable[Path]) -> list[Skill]:
+    """
+    Discover skills from multiple directory roots.
+    """
+    skills_by_name: dict[str, Skill] = {}
+    for skills_dir in skills_dirs:
+        for skill in discover_skills(skills_dir):
+            skills_by_name[normalize_skill_name(skill.name)] = skill
+    return sorted(skills_by_name.values(), key=lambda s: s.name)
+
+
+def read_skill_text(skill: Skill) -> str | None:
+    """Read the SKILL.md contents for a skill."""
+    try:
+        return skill.skill_md_file.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        logger.warning(
+            "Failed to read skill file {path}: {error}",
+            path=skill.skill_md_file,
+            error=exc,
+        )
+        return None
+
+
+class Skill(BaseModel):
+    """Information about a single skill."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str
+    description: str
+    dir: Path
+
+    @property
+    def skill_md_file(self) -> Path:
+        """Path to the SKILL.md file."""
+        return self.dir / "SKILL.md"
+
+
+def discover_skills(skills_dir: Path) -> list[Skill]:
+    """
+    Discover all skills in the given directory.
+
+    Args:
+        skills_dir: Path to the directory containing skills.
+
+    Returns:
+        List of Skill objects, one for each valid skill found.
+    """
+    if not skills_dir.is_dir():
+        return []
+
+    skills: list[Skill] = []
+
+    # Iterate through all subdirectories in the skills directory
+    for skill_dir in skills_dir.iterdir():
+        if not skill_dir.is_dir():
+            continue
+
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+
+        # Try to parse the SKILL.md file
+        try:
+            skills.append(parse_skill_md(skill_md))
+        except Exception as e:
+            # Skip invalid skills, but log for debugging
+            logger.info("Skipping invalid skill at {}: {}", skill_md, e)
+            continue
+
+    return sorted(skills, key=lambda s: s.name)
+
+
+def parse_skill_md(skill_md_file: Path) -> Skill:
+    """
+    Parse a SKILL.md file to extract name and description.
+
+    Args:
+        skill_md_file: Path to the SKILL.md file.
+
+    Returns:
+        Skill object.
+
+    Raises:
+        ValueError: If the SKILL.md file is not valid.
+    """
+    frontmatter = read_frontmatter(skill_md_file) or {}
+
+    if "name" not in frontmatter:
+        frontmatter["name"] = skill_md_file.parent.name
+    if "description" not in frontmatter:
+        frontmatter["description"] = "No description provided."
+
+    return Skill.model_validate(
+        {
+            **frontmatter,
+            "dir": skill_md_file.parent.absolute(),
+        }
+    )

kimi_cli/skills/kimi-cli-help/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: kimi-cli-help
+description: Answer Kimi CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi CLI itself.
+---
+
+# Kimi CLI Help
+
+Help users with Kimi CLI questions by consulting documentation and source code.
+
+## Strategy
+
+1. **Prefer official documentation** for most questions
+2. **Read local source** when in kimi-cli project itself, or when user is developing with kimi-cli as a library (e.g., importing from `kimi_cli` in their code)
+3. **Clone and explore source** for complex internals not covered in docs - **ask user for confirmation first**
+
+## Documentation
+
+Base URL: `https://moonshotai.github.io/kimi-cli/`
+
+Fetch documentation index to find relevant pages:
+
+```
+https://moonshotai.github.io/kimi-cli/llms.txt
+```
+
+### Page URL Pattern
+
+- English: `https://moonshotai.github.io/kimi-cli/en/...`
+- Chinese: `https://moonshotai.github.io/kimi-cli/zh/...`
+
+### Topic Mapping
+
+| Topic | Page |
+|-------|------|
+| Installation, first run | `/en/guides/getting-started.md` |
+| Config files | `/en/configuration/config-files.md` |
+| Providers, models | `/en/configuration/providers.md` |
+| Environment variables | `/en/configuration/env-vars.md` |
+| Slash commands | `/en/reference/slash-commands.md` |
+| CLI flags | `/en/reference/kimi-command.md` |
+| Keyboard shortcuts | `/en/reference/keyboard.md` |
+| MCP | `/en/customization/mcp.md` |
+| Agents | `/en/customization/agents.md` |
+| Skills | `/en/customization/skills.md` |
+| FAQ | `/en/faq.md` |
+
+## Source Code
+
+Repository: `https://github.com/MoonshotAI/kimi-cli`
+
+When to read source:
+
+- In kimi-cli project directory (check `pyproject.toml` for `name = "kimi-cli"`)
+- User is importing `kimi_cli` as a library in their project
+- Question about internals not covered in docs (ask user before cloning)