emdash-core 0.1.7__py3-none-any.whl → 0.1.25__py3-none-any.whl

emdash_core/api/skills.py

@@ -0,0 +1,241 @@
+"""Skill management endpoints."""
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from ..config import get_config
+
+router = APIRouter(prefix="/skills", tags=["skills"])
+
+
+class SkillInfo(BaseModel):
+    """Skill information."""
+    name: str
+    description: str
+    user_invocable: bool
+    tools: list[str]
+    path: str
+    exists: bool
+
+
+class SkillListResponse(BaseModel):
+    """Response for listing skills."""
+    skills: list[SkillInfo]
+    count: int
+
+
+class CreateSkillRequest(BaseModel):
+    """Request to create a skill."""
+    name: str = Field(..., description="Skill name (lowercase, hyphens allowed, max 64 chars)")
+    description: str = Field(..., description="Brief description of when to use this skill")
+    user_invocable: bool = Field(default=True, description="Whether skill can be invoked with /name")
+    tools: list[str] = Field(default=[], description="List of tools this skill needs")
+    instructions: str = Field(default="", description="Skill instructions/content")
+
+
+class CreateSkillResponse(BaseModel):
+    """Response from creating a skill."""
+    success: bool
+    name: str
+    path: Optional[str] = None
+    error: Optional[str] = None
+
+
+class InvokeSkillRequest(BaseModel):
+    """Request to invoke a skill."""
+    args: str = Field(default="", description="Optional arguments for the skill")
+
+
+class InvokeSkillResponse(BaseModel):
+    """Response from invoking a skill."""
+    skill_name: str
+    description: str
+    instructions: str
+    tools: list[str]
+    args: str
+
+
+def _get_skills_dir() -> Path:
+    """Get the skills directory for the current repo."""
+    config = get_config()
+    if config.repo_root:
+        return Path(config.repo_root) / ".emdash" / "skills"
+    return Path.cwd() / ".emdash" / "skills"
+
+
+@router.get("", response_model=SkillListResponse)
+async def list_skills():
+    """List all configured skills.
+
+    Returns skills from the .emdash/skills directory.
+    """
+    from ..agent.skills import SkillRegistry
+
+    skills_dir = _get_skills_dir()
+    registry = SkillRegistry.get_instance()
+
+    # Reload skills to get latest
+    registry.load_skills(skills_dir)
+
+    skills = []
+    for skill in registry.get_all_skills().values():
+        skills.append(SkillInfo(
+            name=skill.name,
+            description=skill.description,
+            user_invocable=skill.user_invocable,
+            tools=skill.tools,
+            path=str(skill.file_path) if skill.file_path else "",
+            exists=True,
+        ))
+
+    return SkillListResponse(skills=skills, count=len(skills))
+
+
+@router.post("", response_model=CreateSkillResponse)
+async def create_skill(request: CreateSkillRequest):
+    """Create a new skill.
+
+    Creates a skill directory with SKILL.md in .emdash/skills/
+    """
+    # Validate name
+    name = request.name.lower().strip()
+    if len(name) > 64:
+        raise HTTPException(
+            status_code=400,
+            detail="Skill name must be 64 characters or less"
+        )
+
+    if not name.replace("-", "").replace("_", "").isalnum():
+        raise HTTPException(
+            status_code=400,
+            detail="Skill name must contain only lowercase letters, numbers, hyphens, and underscores"
+        )
+
+    skills_dir = _get_skills_dir()
+    skill_dir = skills_dir / name
+    skill_file = skill_dir / "SKILL.md"
+
+    if skill_dir.exists():
+        raise HTTPException(
+            status_code=409,
+            detail=f"Skill '{name}' already exists"
+        )
+
+    # Build frontmatter
+    tools_str = ", ".join(request.tools) if request.tools else ""
+
+    content = f"""---
+name: {name}
+description: {request.description}
+user_invocable: {str(request.user_invocable).lower()}
+tools: [{tools_str}]
+---
+
+# {name.replace('-', ' ').title()}
+
+{request.instructions if request.instructions else f"Instructions for {name} skill."}
+
+## Usage
+
+Describe how this skill should be used.
+
+## Examples
+
+Provide example scenarios here.
+"""
+
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        skill_file.write_text(content)
+        return CreateSkillResponse(
+            success=True,
+            name=name,
+            path=str(skill_file),
+        )
+    except Exception as e:
+        return CreateSkillResponse(
+            success=False,
+            name=name,
+            error=str(e),
+        )
+
+
+@router.get("/{name}", response_model=SkillInfo)
+async def get_skill(name: str):
+    """Get a specific skill's information."""
+    from ..agent.skills import SkillRegistry
+
+    skills_dir = _get_skills_dir()
+    registry = SkillRegistry.get_instance()
+    registry.load_skills(skills_dir)
+
+    skill = registry.get_skill(name)
+
+    if skill is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Skill '{name}' not found"
+        )
+
+    return SkillInfo(
+        name=skill.name,
+        description=skill.description,
+        user_invocable=skill.user_invocable,
+        tools=skill.tools,
+        path=str(skill.file_path) if skill.file_path else "",
+        exists=True,
+    )
+
+
+@router.delete("/{name}")
+async def delete_skill(name: str):
+    """Delete a skill."""
+    skills_dir = _get_skills_dir()
+    skill_dir = skills_dir / name
+
+    if not skill_dir.exists():
+        raise HTTPException(
+            status_code=404,
+            detail=f"Skill '{name}' not found"
+        )
+
+    import shutil
+    shutil.rmtree(skill_dir)
+
+    # Reset registry to remove cached skill
+    from ..agent.skills import SkillRegistry
+    SkillRegistry.reset()
+
+    return {"deleted": True, "name": name}
+
+
+@router.post("/{name}/invoke", response_model=InvokeSkillResponse)
+async def invoke_skill(name: str, request: InvokeSkillRequest):
+    """Invoke a skill and get its instructions.
+
+    Returns the skill's instructions for the agent to follow.
+    """
+    from ..agent.skills import SkillRegistry
+
+    skills_dir = _get_skills_dir()
+    registry = SkillRegistry.get_instance()
+    registry.load_skills(skills_dir)
+
+    skill = registry.get_skill(name)
+
+    if skill is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Skill '{name}' not found"
+        )
+
+    return InvokeSkillResponse(
+        skill_name=skill.name,
+        description=skill.description,
+        instructions=skill.instructions,
+        tools=skill.tools,
+        args=request.args,
+    )

emdash_core/checkpoint/__init__.py

@@ -0,0 +1,40 @@
+"""Checkpoint module for git-based agent checkpoints.
+
+This module provides automatic checkpoint creation after each agentic
+loop completes, storing file changes as git commits with metadata.
+
+Example:
+    from emdash_core.checkpoint import CheckpointManager
+
+    manager = CheckpointManager(repo_root=Path("."))
+
+    # Create checkpoint after agent run
+    checkpoint = manager.create_checkpoint(
+        messages=runner._messages,
+        model=runner.model,
+        system_prompt=runner.system_prompt,
+        tools_used=["read_file", "write_to_file"],
+        token_usage={"input": 1000, "output": 500},
+    )
+
+    # List checkpoints
+    for cp in manager.list_checkpoints():
+        print(f"{cp.id}: {cp.summary}")
+
+    # Restore to checkpoint
+    conv = manager.restore_checkpoint("cp_abc123_001")
+"""
+
+from .manager import CheckpointManager
+from .models import CheckpointMetadata, ConversationState, CheckpointIndex
+from .storage import CheckpointStorage
+from .git_operations import GitCheckpointOperations
+
+__all__ = [
+    "CheckpointManager",
+    "CheckpointMetadata",
+    "ConversationState",
+    "CheckpointIndex",
+    "CheckpointStorage",
+    "GitCheckpointOperations",
+]

emdash_core/checkpoint/cli.py

@@ -0,0 +1,175 @@
+"""CLI commands for checkpoint management."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .manager import CheckpointManager
+from .storage import CheckpointStorage
+
+
+def find_repo_root() -> Path:
+    """Find the git repository root from current directory."""
+    current = Path.cwd()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return current
+        current = current.parent
+    return Path.cwd()
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List available checkpoints."""
+    repo_root = find_repo_root()
+    storage = CheckpointStorage(repo_root)
+    checkpoints = storage.get_checkpoints(
+        session_id=args.session,
+        limit=args.limit,
+    )
+
+    if not checkpoints:
+        print("No checkpoints found.")
+        return 0
+
+    if args.format == "json":
+        print(json.dumps([cp.to_dict() for cp in checkpoints], indent=2))
+    else:
+        # Table format
+        print(f"{'ID':<20} {'Session':<10} {'Iter':>4} {'Timestamp':<20} {'Summary':<40} {'Commit':<8}")
+        print("-" * 110)
+        for cp in checkpoints:
+            summary = cp.summary[:37] + "..." if len(cp.summary) > 40 else cp.summary
+            commit = cp.commit_sha[:8] if cp.commit_sha else "N/A"
+            print(f"{cp.id:<20} {cp.session_id:<10} {cp.iteration:>4} {cp.timestamp[:19]:<20} {summary:<40} {commit:<8}")
+
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """Show checkpoint details."""
+    repo_root = find_repo_root()
+    storage = CheckpointStorage(repo_root)
+    metadata = storage.find_checkpoint(args.checkpoint_id)
+
+    if not metadata:
+        print(f"Checkpoint not found: {args.checkpoint_id}", file=sys.stderr)
+        return 1
+
+    print(f"Checkpoint: {metadata.id}")
+    print(f"Session:    {metadata.session_id}")
+    print(f"Iteration:  {metadata.iteration}")
+    print(f"Timestamp:  {metadata.timestamp}")
+    print(f"Commit:     {metadata.commit_sha or 'N/A'}")
+    print(f"Summary:    {metadata.summary}")
+    print(f"Tools Used: {', '.join(metadata.tools_used) or 'None'}")
+    print(f"Files Modified:")
+    for f in metadata.files_modified:
+        print(f"  - {f}")
+    print(f"Token Usage:")
+    for key, value in metadata.token_usage.items():
+        print(f"  - {key}: {value}")
+
+    return 0
+
+
+def cmd_restore(args: argparse.Namespace) -> int:
+    """Restore to a checkpoint."""
+    repo_root = find_repo_root()
+    manager = CheckpointManager(repo_root)
+
+    try:
+        conv_state = manager.restore_checkpoint(
+            args.checkpoint_id,
+            restore_conversation=not args.no_conversation,
+        )
+
+        print(f"Restored to checkpoint {args.checkpoint_id}")
+
+        if conv_state:
+            print(f"Conversation restored with {len(conv_state.messages)} messages")
+            print(f"Model: {conv_state.model}")
+
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    """Show diff between two checkpoints."""
+    repo_root = find_repo_root()
+    storage = CheckpointStorage(repo_root)
+
+    cp1 = storage.find_checkpoint(args.checkpoint1)
+    cp2 = storage.find_checkpoint(args.checkpoint2)
+
+    if not cp1:
+        print(f"Checkpoint not found: {args.checkpoint1}", file=sys.stderr)
+        return 1
+    if not cp2:
+        print(f"Checkpoint not found: {args.checkpoint2}", file=sys.stderr)
+        return 1
+
+    if not cp1.commit_sha or not cp2.commit_sha:
+        print("Cannot diff: one or both checkpoints have no commit SHA", file=sys.stderr)
+        return 1
+
+    # Use git diff
+    import subprocess
+    result = subprocess.run(
+        ["git", "diff", cp1.commit_sha, cp2.commit_sha],
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+    )
+    print(result.stdout)
+    if result.stderr:
+        print(result.stderr, file=sys.stderr)
+
+    return result.returncode
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="emdash-checkpoint",
+        description="Manage emdash checkpoints",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # list command
+    list_parser = subparsers.add_parser("list", help="List available checkpoints")
+    list_parser.add_argument("-s", "--session", help="Filter by session ID")
+    list_parser.add_argument("-n", "--limit", type=int, default=20, help="Number of checkpoints to show")
+    list_parser.add_argument("--format", choices=["table", "json"], default="table", help="Output format")
+    list_parser.set_defaults(func=cmd_list)
+
+    # show command
+    show_parser = subparsers.add_parser("show", help="Show checkpoint details")
+    show_parser.add_argument("checkpoint_id", help="Checkpoint ID to show")
+    show_parser.set_defaults(func=cmd_show)
+
+    # restore command
+    restore_parser = subparsers.add_parser("restore", help="Restore to a checkpoint")
+    restore_parser.add_argument("checkpoint_id", help="Checkpoint ID to restore")
+    restore_parser.add_argument("--no-conversation", action="store_true", help="Skip conversation restore")
+    restore_parser.set_defaults(func=cmd_restore)
+
+    # diff command
+    diff_parser = subparsers.add_parser("diff", help="Show diff between two checkpoints")
+    diff_parser.add_argument("checkpoint1", help="First checkpoint ID")
+    diff_parser.add_argument("checkpoint2", help="Second checkpoint ID")
+    diff_parser.set_defaults(func=cmd_diff)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

emdash_core/checkpoint/git_operations.py

@@ -0,0 +1,250 @@
+"""Git operations for checkpoint system."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from git import Repo
+from git.exc import GitCommandError
+
+from ..utils.logger import log
+from .models import CheckpointMetadata
+
+
+class GitCheckpointOperations:
+    """Handles git operations for checkpoints.
+
+    Creates specially-formatted commits that can be identified
+    and parsed as checkpoints.
+    """
+
+    CHECKPOINT_PREFIX = "[emdash-checkpoint]"
+    METADATA_START = "---EMDASH_METADATA---"
+    METADATA_END = "---END_METADATA---"
+
+    def __init__(self, repo_root: Path):
+        """Initialize git operations.
+
+        Args:
+            repo_root: Root of the git repository
+        """
+        self.repo_root = repo_root.resolve()
+        self.repo = Repo(self.repo_root)
+
+    def has_changes(self) -> bool:
+        """Check if there are uncommitted changes.
+
+        Returns:
+            True if there are staged, unstaged, or untracked changes
+        """
+        return self.repo.is_dirty(untracked_files=True)
+
+    def get_modified_files(self) -> list[str]:
+        """Get list of modified/added/deleted files.
+
+        Returns:
+            List of file paths relative to repo root
+        """
+        files = set()
+
+        # Staged changes
+        for item in self.repo.index.diff("HEAD"):
+            files.add(item.a_path)
+            if item.b_path:
+                files.add(item.b_path)
+
+        # Unstaged changes
+        for item in self.repo.index.diff(None):
+            files.add(item.a_path)
+            if item.b_path:
+                files.add(item.b_path)
+
+        # Untracked files
+        files.update(self.repo.untracked_files)
+
+        return sorted(files)
+
+    def create_checkpoint_commit(
+        self,
+        metadata: CheckpointMetadata,
+        summary: str,
+    ) -> str:
+        """Create a checkpoint commit.
+
+        Stages all changes and creates a commit with structured
+        metadata in the commit message.
+
+        Args:
+            metadata: Checkpoint metadata to include
+            summary: Human-readable summary of changes
+
+        Returns:
+            Commit SHA
+
+        Raises:
+            GitCommandError: If commit fails
+        """
+        # Stage all changes
+        self.repo.git.add("-A")
+
+        # Build commit message
+        message = self._build_commit_message(metadata, summary)
+
+        # Create commit
+        commit = self.repo.index.commit(message)
+        log.info(f"Created checkpoint commit {commit.hexsha[:8]}")
+
+        return commit.hexsha
+
+    def _build_commit_message(
+        self,
+        metadata: CheckpointMetadata,
+        summary: str,
+    ) -> str:
+        """Build the structured commit message.
+
+        Format:
+            [emdash-checkpoint] Auto-checkpoint #{iteration}
+
+            Summary: {summary}
+
+            ---EMDASH_METADATA---
+            {json metadata}
+            ---END_METADATA---
+        """
+        # Build metadata dict (excluding commit_sha which isn't set yet)
+        meta_dict = {
+            "checkpoint_version": "1.0",
+            "id": metadata.id,
+            "session_id": metadata.session_id,
+            "iteration": metadata.iteration,
+            "timestamp": metadata.timestamp,
+            "tools_used": metadata.tools_used,
+            "files_modified": metadata.files_modified,
+            "token_usage": metadata.token_usage,
+        }
+
+        lines = [
+            f"{self.CHECKPOINT_PREFIX} Auto-checkpoint #{metadata.iteration}",
+            "",
+            f"Summary: {summary}",
+            "",
+            self.METADATA_START,
+            json.dumps(meta_dict, indent=2),
+            self.METADATA_END,
+        ]
+
+        return "\n".join(lines)
+
+    def parse_checkpoint_commit(self, commit) -> Optional[CheckpointMetadata]:
+        """Parse checkpoint metadata from a commit.
+
+        Args:
+            commit: Git commit object
+
+        Returns:
+            CheckpointMetadata if commit is a checkpoint, None otherwise
+        """
+        if not commit.message.startswith(self.CHECKPOINT_PREFIX):
+            return None
+
+        try:
+            # Extract JSON between markers
+            message = commit.message
+            start_idx = message.find(self.METADATA_START)
+            end_idx = message.find(self.METADATA_END)
+
+            if start_idx == -1 or end_idx == -1:
+                return None
+
+            json_str = message[start_idx + len(self.METADATA_START):end_idx].strip()
+            data = json.loads(json_str)
+
+            return CheckpointMetadata(
+                id=data.get("id", ""),
+                session_id=data.get("session_id", ""),
+                iteration=data.get("iteration", 0),
+                timestamp=data.get("timestamp", ""),
+                commit_sha=commit.hexsha,
+                summary=self._extract_summary(message),
+                tools_used=data.get("tools_used", []),
+                files_modified=data.get("files_modified", []),
+                token_usage=data.get("token_usage", {}),
+            )
+        except (json.JSONDecodeError, KeyError) as e:
+            log.warning(f"Failed to parse checkpoint commit {commit.hexsha[:8]}: {e}")
+            return None
+
+    def _extract_summary(self, message: str) -> str:
+        """Extract summary line from commit message."""
+        for line in message.split("\n"):
+            if line.startswith("Summary:"):
+                return line[8:].strip()
+        return ""
+
+    def list_checkpoint_commits(self, limit: int = 50) -> list[CheckpointMetadata]:
+        """List all checkpoint commits.
+
+        Args:
+            limit: Maximum number of commits to search
+
+        Returns:
+            List of CheckpointMetadata, most recent first
+        """
+        checkpoints = []
+
+        try:
+            for commit in self.repo.iter_commits(max_count=limit * 2):
+                metadata = self.parse_checkpoint_commit(commit)
+                if metadata:
+                    checkpoints.append(metadata)
+                    if len(checkpoints) >= limit:
+                        break
+        except GitCommandError as e:
+            log.warning(f"Failed to list checkpoint commits: {e}")
+
+        return checkpoints
+
+    def restore_to_commit(self, commit_sha: str, create_branch: bool = True) -> str:
+        """Restore working directory to a specific commit.
+
+        Args:
+            commit_sha: SHA of commit to restore to
+            create_branch: If True, create a branch at the restored state
+
+        Returns:
+            Branch name if created, or commit SHA if detached
+
+        Raises:
+            GitCommandError: If restore fails
+        """
+        # Check for uncommitted changes
+        if self.has_changes():
+            raise GitCommandError(
+                "restore",
+                "Cannot restore: uncommitted changes exist. "
+                "Please commit or stash your changes first.",
+            )
+
+        if create_branch:
+            # Create a new branch at the checkpoint
+            branch_name = f"emdash/restore-{commit_sha[:8]}"
+            self.repo.git.checkout("-b", branch_name, commit_sha)
+            log.info(f"Restored to {commit_sha[:8]} on branch {branch_name}")
+            return branch_name
+        else:
+            # Detached HEAD
+            self.repo.git.checkout(commit_sha)
+            log.info(f"Restored to {commit_sha[:8]} (detached HEAD)")
+            return commit_sha
+
+    def get_commit(self, commit_sha: str):
+        """Get a commit object by SHA.
+
+        Args:
+            commit_sha: Full or partial commit SHA
+
+        Returns:
+            Git commit object
+        """
+        return self.repo.commit(commit_sha)