aury-agent 0.0.4__py3-none-any.whl

aury/agents/skill/loader.py

@@ -0,0 +1,180 @@
+"""SkillLoader - Load skills from filesystem."""
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+from .types import Skill
+
+
+class SkillLoader:
+    """Load and manage skills from the filesystem.
+    
+    Skills are loaded from SKILL.md files with priority:
+    1. project/ - Project-level skills (.aury/skills/)
+    2. user/ - User-level skills (~/.aury/skills/)
+    3. system/ - Built-in skills (framework provided)
+    
+    Same-named skills: higher priority overrides lower.
+    
+    Usage:
+        loader = SkillLoader()
+        await loader.load_from_directory(Path(".aury/skills"), source="project")
+        
+        skill = loader.get("code-review")
+        all_skills = loader.list_all()
+    """
+    
+    def __init__(self) -> None:
+        self._skills: dict[str, Skill] = {}
+    
+    async def load_from_directory(
+        self,
+        directory: Path,
+        source: Literal["user", "project", "system"] = "user",
+    ) -> list[Skill]:
+        """Load skills from a directory.
+        
+        Scans for SKILL.md files and loads them.
+        
+        Args:
+            directory: Directory to scan
+            source: Source identifier for loaded skills
+            
+        Returns:
+            List of loaded skills
+        """
+        loaded: list[Skill] = []
+        
+        if not directory.exists():
+            return loaded
+        
+        for skill_md in directory.rglob("SKILL.md"):
+            try:
+                skill = await self._load_skill(skill_md, source)
+                if skill:
+                    if skill.name not in self._skills:
+                        self._skills[skill.name] = skill
+                        loaded.append(skill)
+            except Exception:
+                continue
+        
+        return loaded
+    
+    async def _load_skill(
+        self,
+        path: Path,
+        source: Literal["user", "project", "system"],
+    ) -> Skill | None:
+        """Load a single skill from SKILL.md."""
+        def _parse() -> tuple[dict[str, Any], str] | None:
+            text = path.read_text(encoding="utf-8")
+            
+            if not text.startswith("---"):
+                return None
+            
+            parts = text.split("---", 2)
+            if len(parts) < 3:
+                return None
+            
+            frontmatter = yaml.safe_load(parts[1])
+            if not frontmatter:
+                return None
+            
+            return frontmatter, parts[2].strip()
+        
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(None, _parse)
+        
+        if not result:
+            return None
+        
+        frontmatter, body = result
+        
+        name = frontmatter.get("name")
+        description = frontmatter.get("description")
+        
+        if not name or not description:
+            return None
+        
+        if not re.match(r"^[a-z][a-z0-9-]*$", name) or len(name) > 64:
+            return None
+        
+        allowed_tools = None
+        if "allowed_tools" in frontmatter:
+            tools_str = frontmatter["allowed_tools"]
+            if isinstance(tools_str, str):
+                allowed_tools = tools_str.split()
+            elif isinstance(tools_str, list):
+                allowed_tools = tools_str
+        
+        return Skill(
+            name=name,
+            description=description.strip(),
+            path=path,
+            source=source,
+            license=frontmatter.get("license"),
+            allowed_tools=allowed_tools,
+            metadata={k: v for k, v in frontmatter.items() 
+                     if k not in ("name", "description", "license", "allowed_tools")},
+            _content=body,
+        )
+    
+    def get(self, name: str) -> Skill | None:
+        """Get skill by name."""
+        return self._skills.get(name)
+    
+    def list_all(self) -> list[Skill]:
+        """Get all registered skills."""
+        return list(self._skills.values())
+    
+    def match(self, query: str) -> list[Skill]:
+        """Fuzzy match skills based on description.
+        
+        Simple keyword matching - can be enhanced with embeddings.
+        """
+        query_lower = query.lower()
+        matches = []
+        
+        for skill in self._skills.values():
+            desc_lower = skill.description.lower()
+            name_lower = skill.name.lower()
+            
+            query_words = query_lower.split()
+            if any(word in desc_lower or word in name_lower for word in query_words):
+                matches.append(skill)
+        
+        return matches
+    
+    def format_for_prompt(self) -> str:
+        """Format skills for system prompt injection.
+        
+        Returns a markdown-formatted list of available skills.
+        """
+        if not self._skills:
+            return ""
+        
+        lines = ["## Available Skills\n"]
+        
+        for skill in sorted(self._skills.values(), key=lambda s: s.name):
+            desc_first_line = skill.description.split("\n")[0].strip()
+            lines.append(f"- **{skill.name}**: {desc_first_line}")
+            lines.append(f"  Path: `{skill.path.parent}`")
+            
+            if skill.allowed_tools:
+                lines.append(f"  Tools: {', '.join(skill.allowed_tools)}")
+            
+            lines.append("")
+        
+        return "\n".join(lines)
+    
+    def clear(self) -> None:
+        """Clear all loaded skills."""
+        self._skills.clear()
+
+
+__all__ = ["SkillLoader"]

aury/agents/skill/types.py

@@ -0,0 +1,83 @@
+"""Skill data types."""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class Skill:
+    """Skill definition.
+    
+    A skill represents a reusable capability that can be loaded into an agent.
+    Skills are defined by SKILL.md files with YAML frontmatter.
+    
+    Attributes:
+        name: Unique identifier (lowercase + hyphens, ≤64 chars)
+        description: Description and trigger conditions (≤1024 chars)
+        path: Path to SKILL.md file
+        source: Origin of the skill (user/project/system)
+        license: Optional license
+        allowed_tools: Pre-authorized tools for this skill
+        metadata: Additional metadata from frontmatter
+    """
+    name: str
+    description: str
+    path: Path
+    source: Literal["user", "project", "system"]
+    
+    # Optional metadata
+    license: str | None = None
+    allowed_tools: list[str] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    # Runtime (lazy loaded)
+    _content: str | None = field(default=None, repr=False)
+    
+    async def load_content(self) -> str:
+        """Load full content (Progressive Disclosure).
+        
+        Lazily loads the body content of SKILL.md when needed.
+        """
+        if self._content is None:
+            self._content = await self._read_body()
+        return self._content
+    
+    async def _read_body(self) -> str:
+        """Read SKILL.md body (after frontmatter)."""
+        def _read() -> str:
+            text = self.path.read_text(encoding="utf-8")
+            if text.startswith("---"):
+                parts = text.split("---", 2)
+                if len(parts) >= 3:
+                    return parts[2].strip()
+            return text
+        
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, _read)
+    
+    def get_resource_path(self, relative: str) -> Path:
+        """Get absolute path for a resource relative to skill directory.
+        
+        Args:
+            relative: Relative path (e.g., "scripts/helper.py")
+            
+        Returns:
+            Absolute path to the resource
+        """
+        return self.path.parent / relative
+    
+    def has_script(self, name: str) -> bool:
+        """Check if skill has a specific script."""
+        script_path = self.get_resource_path(f"scripts/{name}")
+        return script_path.exists()
+    
+    def has_reference(self, name: str) -> bool:
+        """Check if skill has a specific reference document."""
+        ref_path = self.get_resource_path(f"references/{name}")
+        return ref_path.exists()
+
+
+__all__ = ["Skill"]

aury/agents/tool/__init__.py

@@ -0,0 +1,39 @@
+"""Tool system with ToolSet, decorators, and built-in tools."""
+from .set import ToolSet
+from .decorator import tool
+from .builtin import (
+    PlanTool,
+    DelegateTool,
+    YieldResultTool,
+    AskUserTool,
+    ThinkingTool,
+)
+from ..core.types.tool import (
+    BaseTool,
+    ToolInfo,
+    ToolContext,
+    ToolResult,
+    ToolConfig,
+    ToolInvocation,
+    ToolInvocationState,
+)
+
+__all__ = [
+    # Base classes
+    "BaseTool",
+    "ToolInfo",
+    "ToolContext",
+    "ToolResult",
+    "ToolConfig",
+    "ToolInvocation",
+    "ToolInvocationState",
+    # ToolSet and decorators
+    "ToolSet",
+    "tool",
+    # Built-in tools
+    "PlanTool",
+    "DelegateTool",
+    "YieldResultTool",
+    "AskUserTool",
+    "ThinkingTool",
+]

aury/agents/tool/builtin/__init__.py

@@ -0,0 +1,23 @@
+"""Built-in tools for agents."""
+from .plan import PlanTool
+from .delegate import DelegateTool
+from .yield_result import YieldResultTool
+from .ask_user import AskUserTool
+from .thinking import ThinkingTool
+from .bash import BashTool
+from .read import ReadTool
+from .edit import EditTool
+
+__all__ = [
+    # Control flow tools
+    "PlanTool",
+    "DelegateTool",
+    "YieldResultTool",
+    # HITL tools
+    "AskUserTool",
+    "ThinkingTool",
+    # File/Shell tools
+    "BashTool",
+    "ReadTool",
+    "EditTool",
+]

aury/agents/tool/builtin/ask_user.py

@@ -0,0 +1,155 @@
+"""Ask user tool - human-in-the-loop interaction.
+
+Enables agent to request clarification or confirmation from user.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from ...core.logging import tool_logger as logger
+from ...core.types.tool import BaseTool, ToolContext, ToolResult
+from ...core.types.block import BlockEvent, BlockKind, BlockOp
+
+
+QuestionType = Literal["text", "confirm", "choice"]
+
+
+class AskUserTool(BaseTool):
+    """Request input from the user.
+    
+    Use this tool when you need:
+    - Clarification on ambiguous requirements
+    - Confirmation before destructive operations
+    - User to make a choice between options
+    - Additional information not available in context
+    
+    The tool will pause execution and wait for user response.
+    """
+    
+    _name = "ask_user"
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def description(self) -> str:
+        return """Ask the user a question and wait for their response.
+
+Use this when you need clarification, confirmation, or additional
+information from the user. Supports:
+- text: Open-ended questions
+- confirm: Yes/No questions  
+- choice: Multiple choice selection
+
+The conversation will pause until the user responds."""
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The question to ask the user",
+                },
+                "type": {
+                    "type": "string",
+                    "enum": ["text", "confirm", "choice"],
+                    "description": "Type of response expected",
+                    "default": "text",
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Options for 'choice' type questions",
+                },
+                "default": {
+                    "type": "string",
+                    "description": "Default value if user skips",
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Additional context to help user answer",
+                },
+            },
+            "required": ["question"],
+        }
+    
+    async def execute(
+        self,
+        params: dict[str, Any],
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute ask - request user input."""
+        question = params.get("question", "")
+        q_type: QuestionType = params.get("type", "text")
+        choices = params.get("choices", [])
+        default = params.get("default")
+        context = params.get("context")
+        
+        logger.info(
+            "Asking user",
+            extra={"question": question[:50], "type": q_type},
+        )
+        
+        # Validate choice type has choices
+        if q_type == "choice" and not choices:
+            return ToolResult.error("Choice type questions require 'choices' parameter")
+        
+        # Emit ASK block
+        await self._emit_ask_block(ctx, question, q_type, choices, default, context)
+        
+        # Build display output
+        output_parts = [f"Question: {question}"]
+        if context:
+            output_parts.append(f"Context: {context}")
+        if q_type == "confirm":
+            output_parts.append("Type: Yes/No")
+        elif q_type == "choice" and choices:
+            output_parts.append("Options:")
+            for i, choice in enumerate(choices, 1):
+                output_parts.append(f"  {i}. {choice}")
+        if default:
+            output_parts.append(f"Default: {default}")
+        
+        # Note: Real implementation would:
+        # 1. Emit HITL block/event
+        # 2. Set invocation state to "waiting_for_input"
+        # 3. Pause agent execution
+        # 4. When user responds, resume with answer in context
+        
+        return ToolResult(output="\n".join(output_parts))
+    
+    async def _emit_ask_block(
+        self,
+        ctx: ToolContext,
+        question: str,
+        q_type: QuestionType,
+        choices: list[str],
+        default: str | None,
+        context: str | None,
+    ) -> None:
+        """Emit ASK block."""
+        emit = getattr(ctx, 'emit', None)
+        if emit is None:
+            return
+        
+        block = BlockEvent(
+            kind=BlockKind.ASK,
+            op=BlockOp.APPLY,
+            data={
+                "question": question,
+                "type": q_type,
+                "choices": choices,
+                "default": default,
+                "context": context,
+            },
+            session_id=ctx.session_id,
+            invocation_id=ctx.invocation_id,
+        )
+        
+        await emit(block)
+
+
+__all__ = ["AskUserTool"]

aury/agents/tool/builtin/bash.py

@@ -0,0 +1,107 @@
+"""BashTool - Execute shell commands."""
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from typing import Any
+
+from ...core.types.tool import BaseTool, ToolContext, ToolResult, ToolInfo
+
+
+class BashTool(BaseTool):
+    """Execute shell commands.
+    
+    Provides the ability to run shell commands with timeout and working directory support.
+    
+    Security Note:
+        In production, you should restrict the commands that can be executed,
+        or run in a sandboxed environment.
+    """
+    
+    _name = "bash"
+    _description = "Execute shell commands and return the output"
+    _parameters = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The shell command to execute",
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Timeout in seconds (default: 30)",
+                "default": 30,
+            },
+            "working_dir": {
+                "type": "string",
+                "description": "Working directory for the command (optional)",
+            },
+        },
+        "required": ["command"],
+    }
+    
+    def __init__(self, allowed_commands: list[str] | None = None):
+        """Initialize BashTool.
+        
+        Args:
+            allowed_commands: List of allowed command prefixes (None = allow all)
+        """
+        self._allowed_commands = allowed_commands
+    
+    async def execute(
+        self,
+        params: dict[str, Any],
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute the shell command."""
+        command = params.get("command", "")
+        timeout = params.get("timeout", 30)
+        working_dir = params.get("working_dir")
+        
+        if not command:
+            return ToolResult.error("Command is required")
+        
+        # Security check
+        if self._allowed_commands:
+            cmd_prefix = command.split()[0] if command.split() else ""
+            if cmd_prefix not in self._allowed_commands:
+                return ToolResult.error(f"Command '{cmd_prefix}' is not allowed")
+        
+        try:
+            # Run command
+            process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=working_dir,
+            )
+            
+            try:
+                stdout, stderr = await asyncio.wait_for(
+                    process.communicate(),
+                    timeout=timeout,
+                )
+            except asyncio.TimeoutError:
+                process.kill()
+                return ToolResult.error(f"Command timed out after {timeout} seconds")
+            
+            output = stdout.decode("utf-8", errors="replace")
+            error_output = stderr.decode("utf-8", errors="replace")
+            
+            if process.returncode != 0:
+                return ToolResult(
+                    output=f"Exit code: {process.returncode}\n\nSTDOUT:\n{output}\n\nSTDERR:\n{error_output}",
+                    is_error=True,
+                )
+            
+            result_output = output
+            if error_output:
+                result_output += f"\n\nSTDERR:\n{error_output}"
+            
+            return ToolResult(output=result_output.strip() or "(no output)")
+            
+        except Exception as e:
+            return ToolResult.error(str(e))
+
+
+__all__ = ["BashTool"]