interagent-framework 0.1.0__py3-none-any.whl

interagent/task.py

@@ -0,0 +1,204 @@
+"""Task management for InterAgent."""
+
+import re
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+from .constants import TASKS_ACTIVE_DIR, TASKS_COMPLETED_DIR, TASK_STATUSES, PRIORITIES
+from .utils import load_json, save_json, generate_id, now_iso
+
+
+class TaskStatus(Enum):
+    """Task status enumeration."""
+    PENDING = "pending"
+    ASSIGNED = "assigned"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    UNDER_REVIEW = "under_review"
+    REVISION_NEEDED = "revision_needed"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+class Task:
+    """Represents a task in the system."""
+
+    def __init__(self, data: Dict[str, Any]):
+        """Initialize task with data."""
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        """Get task ID."""
+        return self._data.get("id", "unknown")
+
+    @property
+    def title(self) -> str:
+        """Get task title."""
+        return self._data.get("title", "Untitled")
+
+    @property
+    def status(self) -> str:
+        """Get task status."""
+        return self._data.get("status", "pending")
+
+    @property
+    def assignee(self) -> Optional[str]:
+        """Get task assignee."""
+        return self._data.get("assignee")
+
+    @property
+    def assigner(self) -> Optional[str]:
+        """Get task assigner."""
+        return self._data.get("assigner")
+
+    @property
+    def priority(self) -> str:
+        """Get task priority."""
+        return self._data.get("priority", "medium")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return self._data
+
+    def to_markdown(self) -> str:
+        """Convert to markdown format."""
+        lines = [
+            f"# Task: {self.title}",
+            "",
+            f"**ID:** {self.id}",
+            f"**Status:** {self.status}",
+            f"**Priority:** {self.priority}",
+            f"**Assignee:** {self.assignee or 'Unassigned'}",
+            f"**Assigner:** {self.assigner or 'Unknown'}",
+            "",
+            "## Description",
+            self._data.get("description", "_No description_"),
+            "",
+        ]
+
+        if self._data.get("requirements"):
+            lines.extend(["## Requirements", ""])
+            for req in self._data["requirements"]:
+                lines.append(f"- [ ] {req}")
+            lines.append("")
+
+        if self._data.get("acceptance_criteria"):
+            lines.extend(["## Acceptance Criteria", ""])
+            for crit in self._data["acceptance_criteria"]:
+                lines.append(f"- [ ] {crit}")
+            lines.append("")
+
+        if self._data.get("deliverables"):
+            lines.extend(["## Deliverables", ""])
+            for d in self._data["deliverables"]:
+                lines.append(f"- {d}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    @classmethod
+    def load(cls, task_id: str) -> Optional["Task"]:
+        """Load task by ID."""
+        # Validate task_id format to prevent path traversal
+        if not re.match(r'^[a-zA-Z0-9_-]+$', task_id):
+            return None
+
+        # Try active first
+        filepath = TASKS_ACTIVE_DIR / f"{task_id}.json"
+        data = load_json(filepath)
+        
+        if not data:
+            # Try completed
+            filepath = TASKS_COMPLETED_DIR / f"{task_id}.json"
+            data = load_json(filepath)
+        
+        if data:
+            return cls(data)
+        return None
+
+    def save(self) -> bool:
+        """Save task to file."""
+        filepath = TASKS_ACTIVE_DIR / f"{self.id}.json"
+        return save_json(filepath, self._data)
+
+    def update(self, **kwargs) -> None:
+        """Update task fields."""
+        self._data.update(kwargs)
+        self._data["updated"] = now_iso()
+
+    def move_to_completed(self) -> bool:
+        """Move task from active to completed."""
+        active_path = TASKS_ACTIVE_DIR / f"{self.id}.json"
+        completed_path = TASKS_COMPLETED_DIR / f"{self.id}.json"
+        
+        if active_path.exists():
+            save_json(completed_path, self._data)
+            active_path.unlink()
+            return True
+        return False
+
+    @classmethod
+    def create(
+        cls,
+        title: str,
+        description: str = "",
+        assignee: Optional[str] = None,
+        assigner: Optional[str] = None,
+        priority: str = "medium",
+        requirements: Optional[List[str]] = None,
+        acceptance_criteria: Optional[List[str]] = None,
+    ) -> "Task":
+        """Create a new task."""
+        if priority not in PRIORITIES:
+            priority = "medium"
+
+        data = {
+            "id": generate_id("task"),
+            "title": title,
+            "description": description,
+            "status": "pending",
+            "priority": priority,
+            "assignee": assignee,
+            "assigner": assigner,
+            "created": now_iso(),
+            "updated": now_iso(),
+            "requirements": requirements or [],
+            "acceptance_criteria": acceptance_criteria or [],
+            "deliverables": [],
+            "notes": [],
+        }
+
+        return cls(data)
+
+    @classmethod
+    def list_all(
+        cls,
+        status: Optional[str] = None,
+        assignee: Optional[str] = None,
+        active_only: bool = False,
+    ) -> List["Task"]:
+        """List all tasks matching criteria."""
+        tasks = []
+        
+        # Load active tasks
+        for filepath in TASKS_ACTIVE_DIR.glob("*.json"):
+            data = load_json(filepath)
+            if data:
+                tasks.append(cls(data))
+        
+        # Load completed if not active_only
+        if not active_only:
+            for filepath in TASKS_COMPLETED_DIR.glob("*.json"):
+                data = load_json(filepath)
+                if data:
+                    tasks.append(cls(data))
+        
+        # Filter
+        if status:
+            tasks = [t for t in tasks if t.status == status]
+        if assignee:
+            tasks = [t for t in tasks if t.assignee == assignee]
+        
+        return tasks

interagent/templates/__init__.py

@@ -0,0 +1,35 @@
+"""Templates for InterAgent.
+
+This module contains markdown templates for common collaboration scenarios.
+"""
+
+from pathlib import Path
+
+TEMPLATES_DIR = Path(__file__).parent
+
+
+def get_template(name: str) -> str:
+    """Get a template by name.
+    
+    Args:
+        name: Template name (e.g., 'task_delegation', 'review_request')
+        
+    Returns:
+        Template content as string
+    """
+    template_file = TEMPLATES_DIR / f"{name}.md"
+    if template_file.exists():
+        return template_file.read_text()
+    raise FileNotFoundError(f"Template not found: {name}")
+
+
+def list_templates() -> list:
+    """List available templates.
+    
+    Returns:
+        List of template names
+    """
+    return [f.stem for f in TEMPLATES_DIR.glob("*.md")]
+
+
+__all__ = ["get_template", "list_templates", "TEMPLATES_DIR"]

interagent/templates/review_request.md

@@ -0,0 +1,68 @@
+# Review Request
+
+**Task:** {{ task_title }}  
+**Task ID:** {{ task_id }}  
+**Submitted By:** {{ author }}  
+**Date:** {{ date }}  
+**Requested Reviewer:** {{ reviewer }}
+
+---
+
+## Summary
+
+{{ summary }}
+
+## Changes
+
+{% for change in changes %}
+- **{{ change.file }}**: {{ change.description }}
+{% endfor %}
+
+## Testing
+
+{% if tests %}
+- [x] Tests written and passing
+- Coverage: {{ coverage }}%
+{% else %}
+- [ ] Tests pending
+{% endif %}
+
+## Specific Areas for Review
+
+Please focus on:
+
+{% for area in focus_areas %}
+- [ ] {{ area }}
+{% endfor %}
+
+---
+
+## Review Response Template
+
+**Reviewer:** {{ reviewer }}  
+**Date:** {{ review_date }}
+
+### Overall Assessment
+- [ ] **APPROVED** - Ready to merge
+- [ ] **NEEDS_REVISION** - Changes required
+- [ ] **DISCUSSION_NEEDED** - Need to discuss
+
+### Feedback
+
+**What's Good:**
+{% for good in feedback_good %}
+- {{ good }}
+{% endfor %}
+
+**Suggestions:**
+{% for suggestion in feedback_suggestions %}
+- {{ suggestion }}
+{% endfor %}
+
+**Required Changes (if any):**
+{% for change in required_changes %}
+- [ ] {{ change }}
+{% endfor %}
+
+### Next Steps
+{{ next_steps }}

interagent/templates/task_delegation.md

@@ -0,0 +1,69 @@
+# Task Delegation Template
+
+**From:** {{ sender }} ({{ sender_role }})  
+**To:** {{ recipient }} ({{ recipient_role }})  
+**Date:** {{ date }}  
+**Task ID:** {{ task_id }}
+
+---
+
+## Task: {{ title }}
+
+### Description
+{{ description }}
+
+### Requirements
+{% for req in requirements %}
+- [ ] {{ req }}
+{% endfor %}
+
+### Acceptance Criteria
+{% for criteria in acceptance_criteria %}
+- [ ] {{ criteria }}
+{% endfor %}
+
+### Priority
+{{ priority }}
+
+### Context
+{{ context }}
+
+### Expected Deliverables
+{% for deliverable in deliverables %}
+- [ ] {{ deliverable }}
+{% endfor %}
+
+---
+
+## Expected Response
+
+Please respond with one of:
+
+- ✅ **ACCEPT** - I can complete this task
+- ❌ **REJECT** - I cannot complete this task (explain why)
+- ❓ **CLARIFY** - I need more information
+
+Once accepted, please provide:
+1. Your approach/plan
+2. Estimated time to complete
+3. Any dependencies or blockers
+
+---
+
+## Communication
+
+Use the following to update status:
+
+```bash
+# Start work
+interagent task update {{ task_id }} --status in_progress
+
+# Add note
+interagent task update {{ task_id }} --note "Making progress..."
+
+# Complete
+interagent task update {{ task_id }} --status completed
+
+# Request review
+interagent msg send --to {{ sender }} --subject "Review Request" --message "Task complete!"
+```

interagent/templates/update_prompt.md

@@ -0,0 +1,70 @@
+# Template Update Task
+
+**Date:** {date}
+**Assigned to:** {agent}
+**Focus:** {focus}
+
+## Your Task
+
+You are responsible for keeping the project kickoff template current with the
+latest AI coding best practices and tool capabilities.
+
+## Steps
+
+### 1. Research (search the web)
+
+Search for the following topics - focus on {year}:
+
+- "Claude Code sub-agents best practices {year}"
+- "Kimi Code agents capabilities {year}"
+- "AI coding workflow multi-agent patterns {year}"
+- "Claude Code hooks slash commands new features {year}"
+- Recent Anthropic developer blog posts about Claude Code
+- Recent Moonshot AI / Kimi developer docs about Kimi Code agents
+
+### 2. Review the Current Template
+
+Read the file at: `{template_path}`
+
+Pay attention to:
+- Any commands that reference specific versions or flags
+- Steps that describe Claude Code or Kimi Code behavior
+- The cross-agent sub-agent prompting section
+- The InterAgent CLI commands mentioned
+
+### 3. Identify Improvements
+
+Look for:
+- New sub-agent or tool capabilities in Claude Code or Kimi Code
+- Outdated commands, flags, or workflows
+- Better multi-agent collaboration patterns
+- Improved prompt structures
+- New `interagent` CLI commands that should be documented
+- New cross-agent prompting techniques discovered since the last update
+
+### 4. Update the Template
+
+Edit the file at `{template_path}` with your improvements.
+Rules:
+- Make targeted, minimal changes - do not restructure working sections
+- Update version years (e.g. "2025/2026") if appropriate
+- Add new capabilities where relevant
+- Remove references to features that no longer exist
+
+### 5. Write Change Summary
+
+Create (or overwrite) `TEMPLATE_UPDATE.md` in the same directory as the
+template with:
+- Date of update
+- List of changes made and the reason for each
+- Sources and links you referenced
+- Any open questions or areas that need the user's decision
+
+## Focus Area for This Run
+
+{focus}
+
+## Expected Output
+
+1. Updated `{template_path}`
+2. New `TEMPLATE_UPDATE.md` in the same directory as the template

interagent/utils.py

@@ -0,0 +1,90 @@
+"""Utility functions for InterAgent."""
+
+import json
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .constants import (
+    INTERAGENT_DIR,
+    AGENTS_DIR,
+    TASKS_ACTIVE_DIR,
+    TASKS_COMPLETED_DIR,
+    MESSAGES_PENDING_DIR,
+    MESSAGES_ARCHIVE_DIR,
+    SHARED_DIR,
+)
+
+
+def ensure_dirs() -> None:
+    """Ensure all required directories exist."""
+    for d in [
+        INTERAGENT_DIR,
+        AGENTS_DIR,
+        TASKS_ACTIVE_DIR,
+        TASKS_COMPLETED_DIR,
+        MESSAGES_PENDING_DIR,
+        MESSAGES_ARCHIVE_DIR,
+        SHARED_DIR,
+    ]:
+        d.mkdir(parents=True, exist_ok=True)
+
+
+def generate_id(prefix: str = "id") -> str:
+    """Generate a unique ID with prefix."""
+    return f"{prefix}-{str(uuid.uuid4())[:6]}"
+
+
+def now_iso() -> str:
+    """Get current timestamp in ISO format."""
+    return datetime.now().isoformat()
+
+
+def load_json(filepath: Path) -> Optional[Dict[str, Any]]:
+    """Load JSON from file."""
+    if not filepath.exists():
+        return None
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def save_json(filepath: Path, data: Dict[str, Any]) -> bool:
+    """Save data to JSON file."""
+    try:
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except IOError:
+        return False
+
+
+def list_json_files(directory: Path) -> list:
+    """List all JSON files in directory."""
+    if not directory.exists():
+        return []
+    return sorted(directory.glob("*.json"))
+
+
+def print_success(message: str) -> None:
+    """Print success message."""
+    print(f"[OK] {message}")
+
+
+def print_warning(message: str) -> None:
+    """Print warning message."""
+    print(f"[WARN] {message}")
+
+
+def print_error(message: str) -> None:
+    """Print error message."""
+    print(f"[ERR] {message}")
+
+
+def print_info(message: str) -> None:
+    """Print info message."""
+    print(f"[INFO] {message}")

interagent/validator.py

@@ -0,0 +1,156 @@
+"""JSON schema validation for InterAgent."""
+
+from typing import Any, Dict, List, Tuple
+from .constants import TASK_STATUSES, MESSAGE_TYPES, PRIORITIES, VALID_AGENTS
+
+
+class ValidationError(Exception):
+    """Raised when validation fails."""
+    pass
+
+
+def validate_task(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """Validate task data.
+    
+    Returns:
+        (is_valid, list_of_errors)
+    """
+    errors = []
+    
+    # Required fields
+    required = ["id", "title", "status", "created"]
+    for field in required:
+        if field not in data:
+            errors.append(f"Missing required field: {field}")
+    
+    # Validate status
+    if "status" in data and data["status"] not in TASK_STATUSES:
+        errors.append(f"Invalid status: {data['status']}")
+    
+    # Validate priority
+    if "priority" in data and data["priority"] not in PRIORITIES:
+        errors.append(f"Invalid priority: {data['priority']}")
+    
+    # Validate assignee/assigner
+    if "assignee" in data and data["assignee"]:
+        if data["assignee"] not in VALID_AGENTS:
+            errors.append(f"Invalid assignee: {data['assignee']}")
+    
+    if "assigner" in data and data["assigner"]:
+        if data["assigner"] not in VALID_AGENTS:
+            errors.append(f"Invalid assigner: {data['assigner']}")
+    
+    # Validate types
+    if "title" in data and not isinstance(data["title"], str):
+        errors.append("Title must be a string")
+    
+    if "description" in data and not isinstance(data["description"], str):
+        errors.append("Description must be a string")
+    
+    if "requirements" in data and not isinstance(data["requirements"], list):
+        errors.append("Requirements must be a list")
+    
+    return len(errors) == 0, errors
+
+
+def validate_message(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """Validate message data.
+    
+    Returns:
+        (is_valid, list_of_errors)
+    """
+    errors = []
+    
+    # Required fields
+    required = ["id", "from", "to", "content", "timestamp"]
+    for field in required:
+        if field not in data:
+            errors.append(f"Missing required field: {field}")
+    
+    # Validate sender/recipient
+    if "from" in data and data["from"] not in VALID_AGENTS:
+        errors.append(f"Invalid sender: {data['from']}")
+    
+    if "to" in data and data["to"] not in VALID_AGENTS:
+        errors.append(f"Invalid recipient: {data['to']}")
+    
+    # Validate type
+    if "type" in data and data["type"] not in MESSAGE_TYPES:
+        errors.append(f"Invalid message type: {data['type']}")
+    
+    # Validate types
+    if "content" in data and not isinstance(data["content"], str):
+        errors.append("Content must be a string")
+    
+    if "subject" in data and not isinstance(data["subject"], str):
+        errors.append("Subject must be a string")
+    
+    return len(errors) == 0, errors
+
+
+def validate_session(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """Validate session data."""
+    errors = []
+    
+    required = ["id", "name", "created", "mode", "principal"]
+    for field in required:
+        if field not in data:
+            errors.append(f"Missing required field: {field}")
+    
+    if "mode" in data and data["mode"] not in ["hierarchical", "peer", "review"]:
+        errors.append(f"Invalid mode: {data['mode']}")
+    
+    if "principal" in data and data["principal"] not in VALID_AGENTS:
+        errors.append(f"Invalid principal: {data['principal']}")
+    
+    return len(errors) == 0, errors
+
+
+def sanitize_string(value: Any, max_length: int = 1000) -> str:
+    """Sanitize a string value."""
+    if not isinstance(value, str):
+        return str(value)[:max_length]
+    return value[:max_length]
+
+
+def sanitize_task_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Sanitize task data before saving."""
+    sanitized = {}
+    
+    # Copy allowed fields with sanitization
+    if "id" in data:
+        sanitized["id"] = sanitize_string(data["id"], 50)
+    if "title" in data:
+        sanitized["title"] = sanitize_string(data["title"], 200)
+    if "description" in data:
+        sanitized["description"] = sanitize_string(data["description"], 5000)
+    if "status" in data and data["status"] in TASK_STATUSES:
+        sanitized["status"] = data["status"]
+    if "priority" in data and data["priority"] in PRIORITIES:
+        sanitized["priority"] = data["priority"]
+    if "assignee" in data and data["assignee"] in VALID_AGENTS:
+        sanitized["assignee"] = data["assignee"]
+    if "assigner" in data and data["assigner"] in VALID_AGENTS:
+        sanitized["assigner"] = data["assigner"]
+    
+    # Lists
+    if "requirements" in data and isinstance(data["requirements"], list):
+        sanitized["requirements"] = [
+            sanitize_string(r, 500) for r in data["requirements"]
+        ]
+    if "acceptance_criteria" in data and isinstance(data["acceptance_criteria"], list):
+        sanitized["acceptance_criteria"] = [
+            sanitize_string(c, 500) for c in data["acceptance_criteria"]
+        ]
+    if "deliverables" in data and isinstance(data["deliverables"], list):
+        sanitized["deliverables"] = [
+            sanitize_string(d, 500) for d in data["deliverables"]
+        ]
+    
+    # Timestamps
+    if "created" in data:
+        sanitized["created"] = data["created"]
+    if "updated" in data:
+        sanitized["updated"] = data["updated"]
+    
+    return sanitized