aury-agent 0.0.4__py3-none-any.whl

aury/agents/tool/builtin/edit.py

@@ -0,0 +1,121 @@
+"""EditTool - Edit file contents."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from ...core.types.tool import BaseTool, ToolContext, ToolResult
+
+
+class EditTool(BaseTool):
+    """Edit file contents with multiple modes."""
+    
+    _name = "edit"
+    _description = "Edit file contents (overwrite, append, or insert at line)"
+    _parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path to the file to edit",
+            },
+            "content": {
+                "type": "string",
+                "description": "Content to write",
+            },
+            "mode": {
+                "type": "string",
+                "enum": ["overwrite", "append", "insert"],
+                "description": "Edit mode: overwrite (replace), append (add to end), insert (at line)",
+                "default": "overwrite",
+            },
+            "line": {
+                "type": "integer",
+                "description": "Line number for insert mode (1-indexed)",
+            },
+            "encoding": {
+                "type": "string",
+                "description": "File encoding (default: utf-8)",
+                "default": "utf-8",
+            },
+            "create_dirs": {
+                "type": "boolean",
+                "description": "Create parent directories if needed",
+                "default": True,
+            },
+        },
+        "required": ["path", "content"],
+    }
+    
+    def __init__(self, allowed_paths: list[str] | None = None):
+        """Initialize EditTool.
+        
+        Args:
+            allowed_paths: List of allowed path prefixes (None = allow all)
+        """
+        self._allowed_paths = allowed_paths
+    
+    async def execute(self, params: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        file_path = params.get("path", "")
+        content = params.get("content", "")
+        mode = params.get("mode", "overwrite")
+        line = params.get("line")
+        encoding = params.get("encoding", "utf-8")
+        create_dirs = params.get("create_dirs", True)
+        
+        if not file_path:
+            return ToolResult.error("Path is required")
+        
+        path = Path(file_path).expanduser().resolve()
+        
+        # Security check
+        if self._allowed_paths:
+            if not any(str(path).startswith(p) for p in self._allowed_paths):
+                return ToolResult.error(f"Path not allowed: {path}")
+        
+        try:
+            # Create parent directories
+            if create_dirs and not path.parent.exists():
+                path.parent.mkdir(parents=True, exist_ok=True)
+            
+            if mode == "overwrite":
+                path.write_text(content, encoding=encoding)
+                return ToolResult(output=f"File written ({len(content)} chars)")
+            
+            elif mode == "append":
+                existing = path.read_text(encoding=encoding) if path.exists() else ""
+                path.write_text(existing + content, encoding=encoding)
+                return ToolResult(output=f"Content appended ({len(content)} chars)")
+            
+            elif mode == "insert":
+                if line is None:
+                    return ToolResult.error("Line number required for insert mode")
+                
+                if path.exists():
+                    lines = path.read_text(encoding=encoding).splitlines(keepends=True)
+                else:
+                    lines = []
+                
+                # Pad with empty lines if needed
+                while len(lines) < line - 1:
+                    lines.append("\n")
+                
+                # Insert at position
+                insert_idx = max(0, line - 1)
+                content_lines = content.splitlines(keepends=True)
+                if content_lines and not content_lines[-1].endswith("\n"):
+                    content_lines[-1] += "\n"
+                
+                new_lines = lines[:insert_idx] + content_lines + lines[insert_idx:]
+                path.write_text("".join(new_lines), encoding=encoding)
+                
+                return ToolResult(output=f"Content inserted at line {line} ({len(content_lines)} lines)")
+            
+            else:
+                return ToolResult.error(f"Unknown mode: {mode}")
+            
+        except Exception as e:
+            return ToolResult.error(str(e))
+
+
+__all__ = ["EditTool"]

aury/agents/tool/builtin/plan.py

@@ -0,0 +1,277 @@
+"""Plan tool - manage execution plan with checklist.
+
+Emits PLAN block and manages plan state.
+Combines planning (design) and tracking (checklist) in one tool.
+"""
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from ...core.types.tool import BaseTool, ToolContext, ToolResult
+from ...core.types.block import BlockEvent, BlockKind, BlockOp
+from ...core.types.session import generate_id
+
+
+class PlanTool(BaseTool):
+    """Manage execution plan with checklist.
+    
+    Actions:
+    - create: Create new plan with items
+    - add: Add item to existing plan
+    - check: Mark item as done
+    - uncheck: Mark item as pending
+    - update: Update plan title/summary
+    - view: View current plan
+    """
+    
+    _name = "plan"
+    _description = """Manage your execution plan.
+
+Actions:
+- create: Create a new plan with checklist items
+- add: Add an item to the plan
+- check: Mark an item as completed
+- uncheck: Mark an item as pending
+- update: Update plan title or summary
+- view: View current plan status
+
+Use this to track your progress on complex tasks."""
+
+    _parameters = {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["create", "add", "check", "uncheck", "update", "view"],
+                "description": "Action to perform",
+            },
+            "title": {
+                "type": "string",
+                "description": "Plan title (for create/update)",
+            },
+            "summary": {
+                "type": "string",
+                "description": "Plan summary/notes (for create/update)",
+            },
+            "items": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "title": {"type": "string"},
+                        "note": {"type": "string"},
+                    },
+                    "required": ["title"],
+                },
+                "description": "Checklist items (for create)",
+            },
+            "item": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string"},
+                    "note": {"type": "string"},
+                },
+                "description": "Single item to add (for add)",
+            },
+            "item_id": {
+                "type": "string",
+                "description": "Item ID (for check/uncheck)",
+            },
+        },
+        "required": ["action"],
+    }
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def description(self) -> str:
+        return self._description
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return self._parameters
+    
+    async def execute(
+        self,
+        params: dict[str, Any],
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute plan action."""
+        action = params.get("action", "view")
+        
+        # Storage key
+        key = f"plan:{ctx.session_id}"
+        
+        # Get storage
+        storage = getattr(ctx, 'storage', None)
+        if storage is None:
+            return ToolResult.error("Storage not configured")
+        
+        # Load current plan
+        plan = await storage.get("plan", key) or self._empty_plan()
+        
+        # Execute action
+        if action == "create":
+            plan = await self._create(params, plan)
+        elif action == "add":
+            plan = await self._add(params, plan)
+        elif action == "check":
+            plan = await self._check(params, plan, done=True)
+        elif action == "uncheck":
+            plan = await self._check(params, plan, done=False)
+        elif action == "update":
+            plan = await self._update(params, plan)
+        elif action == "view":
+            pass  # Just return current plan
+        else:
+            return ToolResult.error(f"Unknown action: {action}")
+        
+        # Save plan
+        await storage.set("plan", key, plan)
+        
+        # Emit PLAN block
+        await self._emit_plan_block(ctx, plan, action)
+        
+        # Format output
+        output = self._format_plan(plan)
+        
+        return ToolResult(output=output)
+    
+    def _empty_plan(self) -> dict[str, Any]:
+        """Create empty plan structure."""
+        return {
+            "block_id": None,  # Block ID for emit
+            "title": "",
+            "summary": "",
+            "status": "draft",
+            "items": [],
+        }
+    
+    async def _create(self, params: dict[str, Any], plan: dict) -> dict:
+        """Create new plan."""
+        plan = {
+            "block_id": generate_id("blk"),  # New block_id for new plan
+            "title": params.get("title", "Execution Plan"),
+            "summary": params.get("summary", ""),
+            "status": "in_progress",
+            "items": [],
+        }
+        
+        items = params.get("items", [])
+        for item in items:
+            plan["items"].append({
+                "id": str(uuid4())[:8],
+                "title": item.get("title", ""),
+                "note": item.get("note", ""),
+                "status": "pending",
+            })
+        
+        return plan
+    
+    async def _add(self, params: dict[str, Any], plan: dict) -> dict:
+        """Add item to plan."""
+        item = params.get("item", {})
+        if not item.get("title"):
+            item = {"title": params.get("title", ""), "note": params.get("note", "")}
+        
+        if not item.get("title"):
+            raise ValueError("Item title is required")
+        
+        plan["items"].append({
+            "id": str(uuid4())[:8],
+            "title": item.get("title", ""),
+            "note": item.get("note", ""),
+            "status": "pending",
+        })
+        
+        if plan["status"] == "draft":
+            plan["status"] = "in_progress"
+        
+        return plan
+    
+    async def _check(self, params: dict[str, Any], plan: dict, done: bool) -> dict:
+        """Mark item as done/pending."""
+        item_id = params.get("item_id", "")
+        
+        for item in plan["items"]:
+            if item["id"] == item_id:
+                item["status"] = "done" if done else "pending"
+                break
+        
+        # Update plan status if all done
+        if all(i["status"] == "done" for i in plan["items"]) and plan["items"]:
+            plan["status"] = "done"
+        elif any(i["status"] == "done" for i in plan["items"]):
+            plan["status"] = "in_progress"
+        
+        return plan
+    
+    async def _update(self, params: dict[str, Any], plan: dict) -> dict:
+        """Update plan metadata."""
+        if "title" in params:
+            plan["title"] = params["title"]
+        if "summary" in params:
+            plan["summary"] = params["summary"]
+        return plan
+    
+    async def _emit_plan_block(self, ctx: ToolContext, plan: dict, action: str) -> None:
+        """Emit PLAN block event."""
+        emit = getattr(ctx, 'emit', None)
+        if emit is None:
+            return
+        
+        # Get or generate block_id
+        block_id = plan.get("block_id")
+        if not block_id:
+            block_id = generate_id("blk")
+            plan["block_id"] = block_id
+        
+        op = BlockOp.APPLY if action == "create" else BlockOp.PATCH
+        
+        # Don't include block_id in data (it's metadata)
+        data = {k: v for k, v in plan.items() if k != "block_id"}
+        
+        block = BlockEvent(
+            block_id=block_id,
+            kind=BlockKind.PLAN,
+            op=op,
+            data=data,
+            session_id=ctx.session_id,
+            invocation_id=ctx.invocation_id,
+        )
+        
+        await emit(block)
+    
+    def _format_plan(self, plan: dict) -> str:
+        """Format plan as text."""
+        lines = []
+        
+        if plan["title"]:
+            lines.append(f"# {plan['title']}")
+        
+        if plan["summary"]:
+            lines.append(f"\n{plan['summary']}")
+        
+        lines.append(f"\nStatus: {plan['status']}")
+        
+        if plan["items"]:
+            lines.append("\nChecklist:")
+            for item in plan["items"]:
+                icon = "✓" if item["status"] == "done" else "○"
+                line = f"  [{icon}] {item['title']}"
+                if item.get("note"):
+                    line += f" - {item['note']}"
+                line += f" (id: {item['id']})"
+                lines.append(line)
+        
+        pending = sum(1 for i in plan["items"] if i["status"] == "pending")
+        done = sum(1 for i in plan["items"] if i["status"] == "done")
+        lines.append(f"\nProgress: {done}/{len(plan['items'])} completed")
+        
+        return "\n".join(lines)
+
+
+__all__ = ["PlanTool"]

aury/agents/tool/builtin/read.py

@@ -0,0 +1,91 @@
+"""ReadTool - Read file contents."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ...core.types.tool import BaseTool, ToolContext, ToolResult
+
+
+class ReadTool(BaseTool):
+    """Read file contents with optional line range."""
+    
+    _name = "read"
+    _description = "Read file contents, optionally specifying line range"
+    _parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path to the file to read",
+            },
+            "start_line": {
+                "type": "integer",
+                "description": "Start line number (1-indexed, optional)",
+            },
+            "end_line": {
+                "type": "integer",
+                "description": "End line number (inclusive, optional)",
+            },
+            "encoding": {
+                "type": "string",
+                "description": "File encoding (default: utf-8)",
+                "default": "utf-8",
+            },
+        },
+        "required": ["path"],
+    }
+    
+    def __init__(self, allowed_paths: list[str] | None = None):
+        """Initialize ReadTool.
+        
+        Args:
+            allowed_paths: List of allowed path prefixes (None = allow all)
+        """
+        self._allowed_paths = allowed_paths
+    
+    async def execute(self, params: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        file_path = params.get("path", "")
+        start_line = params.get("start_line")
+        end_line = params.get("end_line")
+        encoding = params.get("encoding", "utf-8")
+        
+        if not file_path:
+            return ToolResult.error("Path is required")
+        
+        path = Path(file_path).expanduser().resolve()
+        
+        # Security check
+        if self._allowed_paths:
+            if not any(str(path).startswith(p) for p in self._allowed_paths):
+                return ToolResult.error(f"Path not allowed: {path}")
+        
+        if not path.exists():
+            return ToolResult.error(f"File not found: {path}")
+        
+        if not path.is_file():
+            return ToolResult.error(f"Not a file: {path}")
+        
+        try:
+            content = path.read_text(encoding=encoding)
+            lines = content.splitlines(keepends=True)
+            
+            # Apply line range
+            if start_line is not None or end_line is not None:
+                start_idx = (start_line - 1) if start_line else 0
+                end_idx = end_line if end_line else len(lines)
+                lines = lines[start_idx:end_idx]
+                
+                # Add line numbers
+                output_lines = []
+                for i, line in enumerate(lines, start=start_idx + 1):
+                    output_lines.append(f"{i:4d}| {line.rstrip()}")
+                content = "\n".join(output_lines)
+            
+            return ToolResult(output=content or "(empty file)")
+            
+        except Exception as e:
+            return ToolResult.error(str(e))
+
+
+__all__ = ["ReadTool"]

aury/agents/tool/builtin/thinking.py

@@ -0,0 +1,111 @@
+"""Thinking tool - emit reasoning process.
+
+Allows agent to externalize its thinking/reasoning process.
+Useful for transparency, debugging, and chain-of-thought.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...core.logging import tool_logger as logger
+from ...core.types.tool import BaseTool, ToolContext, ToolResult
+from ...core.types.block import BlockEvent, BlockKind, BlockOp
+
+
+class ThinkingTool(BaseTool):
+    """Emit thinking/reasoning process.
+    
+    Use this tool to externalize your reasoning:
+    - Breaking down complex problems
+    - Weighing options and trade-offs
+    - Planning approach before acting
+    - Explaining decision rationale
+    
+    This creates a THINKING block in the output stream,
+    making reasoning visible to users and useful for debugging.
+    """
+    
+    _name = "thinking"
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def description(self) -> str:
+        return """Emit your thinking/reasoning process.
+
+Use this to externalize your thought process:
+- Analyzing a problem
+- Weighing options
+- Planning an approach
+- Explaining decisions
+
+This makes your reasoning visible and traceable."""
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "thought": {
+                    "type": "string",
+                    "description": "Your thinking/reasoning content",
+                },
+                "category": {
+                    "type": "string",
+                    "enum": ["analysis", "planning", "decision", "reflection", "observation"],
+                    "description": "Category of thinking",
+                    "default": "analysis",
+                },
+            },
+            "required": ["thought"],
+        }
+    
+    async def execute(
+        self,
+        params: dict[str, Any],
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute thinking - emit reasoning block."""
+        thought = params.get("thought", "")
+        category = params.get("category", "analysis")
+        
+        logger.debug(
+            "Agent thinking",
+            extra={"category": category, "length": len(thought)},
+        )
+        
+        # Emit THINKING block
+        await self._emit_thinking_block(ctx, thought, category)
+        
+        # Thinking doesn't produce actionable output
+        # It's purely for transparency/logging
+        return ToolResult(output=thought)
+    
+    async def _emit_thinking_block(
+        self,
+        ctx: ToolContext,
+        thought: str,
+        category: str,
+    ) -> None:
+        """Emit THINKING block."""
+        emit = getattr(ctx, 'emit', None)
+        if emit is None:
+            return
+        
+        block = BlockEvent(
+            kind=BlockKind.THINKING,
+            op=BlockOp.APPLY,
+            data={
+                "thought": thought,
+                "category": category,
+            },
+            session_id=ctx.session_id,
+            invocation_id=ctx.invocation_id,
+        )
+        
+        await emit(block)
+
+
+__all__ = ["ThinkingTool"]