agentpool 2.1.9__py3-none-any.whl

agentpool/sessions/store.py

@@ -0,0 +1,163 @@
+"""Session store protocol and implementations."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+from agentpool.log import get_logger
+
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from agentpool.sessions.models import SessionData
+
+logger = get_logger(__name__)
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    """Protocol for session persistence backends.
+
+    Implementations handle storing and retrieving SessionData to/from
+    various backends (SQL, file, memory, etc.).
+    """
+
+    async def __aenter__(self) -> Self:
+        """Initialize store resources."""
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Clean up store resources."""
+        ...
+
+    @abstractmethod
+    async def save(self, data: SessionData) -> None:
+        """Save or update session data.
+
+        Args:
+            data: Session data to persist
+        """
+        ...
+
+    @abstractmethod
+    async def load(self, session_id: str) -> SessionData | None:
+        """Load session data by ID.
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            Session data if found, None otherwise
+        """
+        ...
+
+    @abstractmethod
+    async def delete(self, session_id: str) -> bool:
+        """Delete a session.
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            True if session was deleted, False if not found
+        """
+        ...
+
+    @abstractmethod
+    async def list_sessions(
+        self,
+        pool_id: str | None = None,
+        agent_name: str | None = None,
+    ) -> list[str]:
+        """List session IDs, optionally filtered.
+
+        Args:
+            pool_id: Filter by pool/manifest ID
+            agent_name: Filter by agent name
+
+        Returns:
+            List of session IDs
+        """
+        ...
+
+    @abstractmethod
+    async def cleanup_expired(self, max_age_hours: int = 24) -> int:
+        """Remove sessions older than max_age.
+
+        Args:
+            max_age_hours: Maximum session age in hours
+
+        Returns:
+            Number of sessions removed
+        """
+        ...
+
+
+class MemorySessionStore:
+    """In-memory session store for testing and development."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, SessionData] = {}
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        pass
+
+    async def save(self, data: SessionData) -> None:
+        self._sessions[data.session_id] = data
+        logger.debug("Saved session", session_id=data.session_id)
+
+    async def load(self, session_id: str) -> SessionData | None:
+        return self._sessions.get(session_id)
+
+    async def delete(self, session_id: str) -> bool:
+        if session_id in self._sessions:
+            del self._sessions[session_id]
+            logger.debug("Deleted session", session_id=session_id)
+            return True
+        return False
+
+    async def list_sessions(
+        self,
+        pool_id: str | None = None,
+        agent_name: str | None = None,
+    ) -> list[str]:
+        result = []
+        for session_id, data in self._sessions.items():
+            if pool_id is not None and data.pool_id != pool_id:
+                continue
+            if agent_name is not None and data.agent_name != agent_name:
+                continue
+            result.append(session_id)
+        return result
+
+    async def cleanup_expired(self, max_age_hours: int = 24) -> int:
+        from agentpool.utils.now import get_now
+
+        now = get_now()
+        expired = []
+        for session_id, data in self._sessions.items():
+            age_hours = (now - data.last_active).total_seconds() / 3600
+            if age_hours > max_age_hours:
+                expired.append(session_id)
+
+        for session_id in expired:
+            del self._sessions[session_id]
+
+        if expired:
+            logger.info("Cleaned up expired sessions", count=len(expired))
+        return len(expired)

agentpool/skills/__init__.py

@@ -0,0 +1,5 @@
+"""Skills package for Claude Code Skills support."""
+
+from agentpool.skills.manager import SkillsManager
+
+__all__ = ["SkillsManager"]

agentpool/skills/manager.py

@@ -0,0 +1,120 @@
+"""Skills manager for pool-wide management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from upathtools import to_upath
+
+from agentpool.log import get_logger
+from agentpool.skills.registry import SkillsRegistry
+
+
+if TYPE_CHECKING:
+    from fsspec import AbstractFileSystem
+    from upathtools import JoinablePathLike
+
+    from agentpool.skills.skill import Skill
+
+
+logger = get_logger(__name__)
+
+
+class SkillsManager:
+    """Pool-wide skills registry management.
+
+    Owns the single skills registry for the pool. Skills can be discovered
+    from multiple directories. The actual `load_skill` tool is provided
+    separately via SkillsTools toolset.
+    """
+
+    def __init__(
+        self,
+        name: str = "skills",
+        owner: str | None = None,
+        skills_dirs: list[JoinablePathLike] | None = None,
+    ) -> None:
+        """Initialize the skills manager.
+
+        Args:
+            name: Name for this manager
+            owner: Owner of this manager
+            skills_dirs: Directories to search for skills
+        """
+        self.name = name
+        self.owner = owner
+        self.registry = SkillsRegistry(skills_dirs)
+        self._initialized = False
+
+    def __repr__(self) -> str:
+        skill_count = len(self.registry.list_items()) if self._initialized else "?"
+        return f"SkillsManager(name={self.name!r}, skills={skill_count})"
+
+    async def __aenter__(self) -> Self:
+        """Initialize the skills manager and discover skills."""
+        try:
+            await self.registry.discover_skills()
+            self._initialized = True
+            count = len(self.registry.list_items())
+            logger.info("Skills manager initialized", name=self.name, skill_count=count)
+        except Exception as e:
+            msg = "Failed to initialize skills manager"
+            logger.exception(msg, name=self.name, error=e)
+            raise
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Clean up the skills manager."""
+        # Skills are file-based, no persistent connections to clean up
+
+    @overload
+    async def add_skills_directory(self, path: JoinablePathLike) -> None: ...
+
+    @overload
+    async def add_skills_directory(self, path: str, *, fs: AbstractFileSystem) -> None: ...
+
+    async def add_skills_directory(
+        self,
+        path: JoinablePathLike,
+        *,
+        fs: AbstractFileSystem | None = None,
+    ) -> None:
+        """Add a new skills directory and discover its skills.
+
+        Args:
+            path: Path to directory containing skills.
+            fs: Optional filesystem instance. When provided, path is interpreted
+                as a path within this filesystem (e.g., ".claude/skills").
+        """
+        if fs is not None:
+            # Pass filesystem directly to registry with the path
+            await self.registry.register_skills_from_path(fs, base_path=str(path))
+            logger.info(
+                "Added skills directory from filesystem",
+                protocol=fs.protocol,
+                path=path,
+            )
+        else:
+            upath = to_upath(path)
+            if upath not in self.registry.skills_dirs:
+                self.registry.skills_dirs.append(upath)
+                await self.registry.register_skills_from_path(upath)
+                logger.info("Added skills directory", path=str(path))
+
+    async def refresh(self) -> None:
+        """Force rediscovery of all skills."""
+        await self.registry.discover_skills()
+        skill_count = len(self.registry.list_items())
+        logger.info("Skills refreshed", name=self.name, skill_count=skill_count)
+
+    def list_skills(self) -> list[Skill]:
+        """Get all available skills."""
+        return [self.registry.get(name) for name in self.registry.list_items()]
+
+    def get_skill(self, name: str) -> Skill:
+        """Get a skill by name."""
+        return self.registry.get(name)
+
+    def get_skill_instructions(self, skill_name: str) -> str:
+        """Get full instructions for a specific skill."""
+        return self.registry.get_skill_instructions(skill_name)

agentpool/skills/registry.py

@@ -0,0 +1,210 @@
+"""Claude Code Skills registry with auto-discovery."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from fsspec import AbstractFileSystem
+from fsspec.asyn import AsyncFileSystem
+from fsspec.implementations.asyn_wrapper import (
+    AsyncFileSystemWrapper,
+)
+from upathtools import is_directory
+from upathtools.helpers import to_upath, upath_to_fs
+
+from agentpool.log import get_logger
+from agentpool.skills.skill import Skill
+from agentpool.tools.exceptions import ToolError
+from agentpool.utils.baseregistry import BaseRegistry
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from upathtools import JoinablePathLike, UPath
+
+
+SKILL_NAME_LIMIT = 64
+SKILL_DESCRIPTION_LIMIT = 1024
+logger = get_logger(__name__)
+
+
+class SkillsRegistry(BaseRegistry[str, Skill]):
+    """Registry for Claude Code Skills with auto-discovery."""
+
+    DEFAULT_SKILL_PATHS: ClassVar = ["~/.claude/skills/", ".claude/skills/"]
+
+    def __init__(self, skills_dirs: Sequence[JoinablePathLike] | None = None) -> None:
+        """Initialize with custom skill directories or auto-detect."""
+        super().__init__()
+        if skills_dirs:
+            self.skills_dirs = [to_upath(i) for i in skills_dirs or []]
+        else:
+            self.skills_dirs = [to_upath(i) for i in self.DEFAULT_SKILL_PATHS or []]
+
+    async def discover_skills(self) -> None:
+        """Scan filesystem and register all found skills.
+
+        Args:
+            filesystem: Optional async filesystem to use. If None, will use upath_to_fs()
+                       to get appropriate filesystem for each skills directory.
+        """
+        for skills_dir in self.skills_dirs:
+            await self.register_skills_from_path(skills_dir)
+
+    async def register_skills_from_path(
+        self,
+        skills_dir: JoinablePathLike | AbstractFileSystem,
+        base_path: str | None = None,
+        **storage_options: Any,
+    ) -> None:
+        """Register skills from a given path.
+
+        Args:
+            skills_dir: Path to the directory containing skills, or filesystem instance.
+            base_path: When skills_dir is a filesystem, the path within that filesystem
+                      to look for skills. Defaults to root_marker if not specified.
+            storage_options: Additional options to pass to the filesystem.
+        """
+        if isinstance(skills_dir, AbstractFileSystem):
+            fs = skills_dir
+            if not isinstance(fs, AsyncFileSystem):
+                fs = AsyncFileSystemWrapper(fs)
+            search_path = base_path if base_path is not None else fs.root_marker
+        else:
+            fs = upath_to_fs(skills_dir, **storage_options)
+            search_path = fs.root_marker
+
+        try:
+            # List entries in skills directory
+            entries = await fs._ls(search_path, detail=True)
+        except FileNotFoundError:
+            logger.warning("Skills directory not found", path=search_path)
+            return
+        # Filter for directories that might contain skills
+        skill_dirs = [
+            entry
+            for entry in entries
+            if await is_directory(fs, entry["name"], entry_type=entry.get("type"))
+        ]
+        if not skill_dirs:
+            logger.info("No skills found", skills_dir=search_path)
+            return
+        logger.info("Found skills", skills=skill_dirs, skills_dir=search_path)
+        for skill_entry in skill_dirs:
+            skill_name = skill_entry["name"].lstrip("./")
+            # Construct full path for skill directory
+            if search_path and search_path != fs.root_marker:
+                skill_dir_path = to_upath(f"{search_path}/{skill_name}")
+                skill_md_path = f"{search_path}/{skill_name}/SKILL.md"
+            else:
+                skill_dir_path = to_upath(skill_name)
+                skill_md_path = f"{skill_name}/SKILL.md"
+            try:
+                await fs._cat_file(skill_md_path)
+            except FileNotFoundError:
+                continue
+
+            try:
+                skill = self._parse_skill(skill_dir_path)
+                self.register(skill.name, skill, replace=True)
+            except Exception as e:  # noqa: BLE001
+                # Log but don't fail discovery for one bad skill
+                print(f"Warning: Failed to parse skill at {skill_dir_path}: {e}")
+
+    def _parse_skill(self, skill_dir: JoinablePathLike) -> Skill:
+        """Parse a SKILL.md file and extract metadata."""
+        skill_file = to_upath(skill_dir) / "SKILL.md"
+        content = skill_file.read_text("utf-8")
+
+        # Extract YAML frontmatter
+        frontmatter_match = re.match(r"^---\s*\n(.*?)\n---\s*\n", content, re.DOTALL)
+        if not frontmatter_match:
+            msg = f"No YAML frontmatter found in {skill_file}"
+            raise ToolError(msg)
+        import yamling
+
+        try:
+            metadata = yamling.load_yaml(frontmatter_match.group(1))
+        except yamling.YAMLError as e:
+            msg = f"Invalid YAML frontmatter in {skill_file}: {e}"
+            raise ToolError(msg) from e
+
+        # Validate required fields
+        if not isinstance(metadata, dict):
+            msg = f"YAML frontmatter must be a dictionary in {skill_file}"
+            raise ToolError(msg)
+
+        name = metadata.get("name")
+        description = metadata.get("description")
+
+        if not name:
+            msg = f"Missing 'name' field in {skill_file}"
+            raise ToolError(msg)
+        if not description:
+            msg = f"Missing 'description' field in {skill_file}"
+            raise ToolError(msg)
+
+        # Validate limits
+        if len(name) > SKILL_NAME_LIMIT:
+            msg = f"{skill_file}: Skill name exceeds {SKILL_NAME_LIMIT} chars"
+            raise ToolError(msg)
+        if len(description) > SKILL_DESCRIPTION_LIMIT:
+            msg = f"{skill_file}: Skill description exceeds {SKILL_DESCRIPTION_LIMIT} chars"
+            raise ToolError(msg)
+
+        return Skill(name=name, description=description, skill_path=to_upath(skill_dir))
+
+    @property
+    def _error_class(self) -> type[ToolError]:
+        """Error class to use for this registry."""
+        return ToolError
+
+    def _validate_item(self, item: Any) -> Skill:
+        """Validate and possibly transform item before registration."""
+        if not isinstance(item, Skill):
+            msg = f"Expected Skill instance, got {type(item)}"
+            raise ToolError(msg)
+        return item
+
+    def get_skill_instructions(self, skill_name: str) -> str:
+        """Lazy load full instructions for a skill."""
+        skill = self.get(skill_name)
+        return skill.load_instructions()
+
+
+if __name__ == "__main__":
+    import os
+
+    import anyio
+    from upathtools import UPath
+
+    from agentpool.log import configure_logging
+
+    configure_logging()
+
+    async def main() -> None:
+        reg = SkillsRegistry()
+        p = UPath(
+            "github://",
+            token=os.getenv("GITHUB_TOKEN"),
+            username="phil65",
+            org="anthropics",
+            repo="skills",
+        )
+        print("Repository contents:")
+        print([f.name for f in p.iterdir()][:5])  # Show first 5 items
+
+        await reg.register_skills_from_path(
+            p,
+            token=os.getenv("GITHUB_TOKEN"),
+            username="phil65",
+            org="anthropics",
+            repo="skills",
+        )
+        print(f"Found {len(reg)} skills:")
+        for name, skill in reg.items():
+            print(f"  - {name}: {skill.description[:60]}...")
+
+    anyio.run(main)

agentpool/skills/skill.py

@@ -0,0 +1,36 @@
+"""Claude Code Skill."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from upathtools import UPath
+
+
+@dataclass
+class Skill:
+    """A Claude Code Skill with metadata and lazy-loaded instructions."""
+
+    name: str
+    description: str
+    skill_path: UPath
+    instructions: str | None = None
+
+    def load_instructions(self) -> str:
+        """Lazy load full instructions from SKILL.md."""
+        if self.instructions is None:
+            skill_file = self.skill_path / "SKILL.md"
+            if skill_file.exists():
+                content = skill_file.read_text(encoding="utf-8")
+                # Split on first --- after frontmatter
+                parts = content.split("---", 2)
+                if len(parts) >= 3:  # noqa: PLR2004
+                    self.instructions = parts[2].strip()
+                else:
+                    self.instructions = ""
+            else:
+                self.instructions = ""
+        return self.instructions

agentpool/storage/__init__.py

@@ -0,0 +1,17 @@
+"""Storage package."""
+
+from agentpool.storage.manager import StorageManager
+from agentpool.storage.serialization import (
+    deserialize_messages,
+    deserialize_parts,
+    serialize_messages,
+    serialize_parts,
+)
+
+__all__ = [
+    "StorageManager",
+    "deserialize_messages",
+    "deserialize_parts",
+    "serialize_messages",
+    "serialize_parts",
+]