flowly-code 1.0.0__py3-none-any.whl

flowly_code/agent/memory.py

@@ -0,0 +1,109 @@
+"""Memory system for persistent agent memory."""
+
+from pathlib import Path
+from datetime import datetime
+
+from flowly_code.utils.helpers import ensure_dir, today_date
+
+
+class MemoryStore:
+    """
+    Memory system for the agent.
+    
+    Supports daily notes (memory/YYYY-MM-DD.md) and long-term memory (MEMORY.md).
+    """
+    
+    def __init__(self, workspace: Path):
+        self.workspace = workspace
+        self.memory_dir = ensure_dir(workspace / "memory")
+        self.memory_file = self.memory_dir / "MEMORY.md"
+    
+    def get_today_file(self) -> Path:
+        """Get path to today's memory file."""
+        return self.memory_dir / f"{today_date()}.md"
+    
+    def read_today(self) -> str:
+        """Read today's memory notes."""
+        today_file = self.get_today_file()
+        if today_file.exists():
+            return today_file.read_text(encoding="utf-8")
+        return ""
+    
+    def append_today(self, content: str) -> None:
+        """Append content to today's memory notes."""
+        today_file = self.get_today_file()
+        
+        if today_file.exists():
+            existing = today_file.read_text(encoding="utf-8")
+            content = existing + "\n" + content
+        else:
+            # Add header for new day
+            header = f"# {today_date()}\n\n"
+            content = header + content
+        
+        today_file.write_text(content, encoding="utf-8")
+    
+    def read_long_term(self) -> str:
+        """Read long-term memory (MEMORY.md)."""
+        if self.memory_file.exists():
+            return self.memory_file.read_text(encoding="utf-8")
+        return ""
+    
+    def write_long_term(self, content: str) -> None:
+        """Write to long-term memory (MEMORY.md)."""
+        self.memory_file.write_text(content, encoding="utf-8")
+    
+    def get_recent_memories(self, days: int = 7) -> str:
+        """
+        Get memories from the last N days.
+        
+        Args:
+            days: Number of days to look back.
+        
+        Returns:
+            Combined memory content.
+        """
+        from datetime import timedelta
+        
+        memories = []
+        today = datetime.now().date()
+        
+        for i in range(days):
+            date = today - timedelta(days=i)
+            date_str = date.strftime("%Y-%m-%d")
+            file_path = self.memory_dir / f"{date_str}.md"
+            
+            if file_path.exists():
+                content = file_path.read_text(encoding="utf-8")
+                memories.append(content)
+        
+        return "\n\n---\n\n".join(memories)
+    
+    def list_memory_files(self) -> list[Path]:
+        """List all memory files sorted by date (newest first)."""
+        if not self.memory_dir.exists():
+            return []
+        
+        files = list(self.memory_dir.glob("????-??-??.md"))
+        return sorted(files, reverse=True)
+    
+    def get_memory_context(self) -> str:
+        """
+        Get memory context for the agent.
+        
+        Returns:
+            Formatted memory context including long-term and recent memories.
+        """
+        parts = []
+        
+        # Long-term memory
+        long_term = self.read_long_term()
+        if long_term:
+            parts.append("## Long-term Memory\n" + long_term)
+        
+        # Today's notes
+        today = self.read_today()
+        if today:
+            parts.append("## Today's Notes\n" + today)
+        
+        return "\n\n".join(parts) if parts else ""

flowly_code/agent/skills.py

@@ -0,0 +1,259 @@
+"""Skills loader for agent capabilities."""
+
+import json
+import os
+import platform
+import re
+import shutil
+from pathlib import Path
+
+# Default builtin skills directory (relative to this file)
+BUILTIN_SKILLS_DIR = Path(__file__).parent.parent / "skills"
+
+# Managed skills directory (installed via flowly-hub)
+MANAGED_SKILLS_DIR = Path.home() / ".flowly" / "skills"
+
+
+class SkillsLoader:
+    """
+    Loader for agent skills.
+
+    Skills are markdown files (SKILL.md) that teach the agent how to use
+    specific tools or perform certain tasks.
+
+    Loading priority (highest to lowest):
+    1. Workspace skills (<workspace>/skills/)
+    2. Managed skills (~/.flowly/skills/) - installed via flowly-hub
+    3. Builtin skills (bundled with package)
+    """
+
+    def __init__(self, workspace: Path, builtin_skills_dir: Path | None = None):
+        self.workspace = workspace
+        self.workspace_skills = workspace / "skills"
+        self.managed_skills = MANAGED_SKILLS_DIR
+        self.builtin_skills = builtin_skills_dir or BUILTIN_SKILLS_DIR
+    
+    def list_skills(self, filter_unavailable: bool = True) -> list[dict[str, str]]:
+        """
+        List all available skills.
+
+        Args:
+            filter_unavailable: If True, filter out skills with unmet requirements.
+
+        Returns:
+            List of skill info dicts with 'name', 'path', 'source'.
+        """
+        skills = []
+
+        # Workspace skills (highest priority)
+        if self.workspace_skills.exists():
+            for skill_dir in self.workspace_skills.iterdir():
+                if skill_dir.is_dir():
+                    skill_file = skill_dir / "SKILL.md"
+                    if skill_file.exists():
+                        skills.append({"name": skill_dir.name, "path": str(skill_file), "source": "workspace"})
+
+        # Managed skills (installed via flowly-hub)
+        if self.managed_skills.exists():
+            for skill_dir in self.managed_skills.iterdir():
+                if skill_dir.is_dir():
+                    skill_file = skill_dir / "SKILL.md"
+                    if skill_file.exists() and not any(s["name"] == skill_dir.name for s in skills):
+                        skills.append({"name": skill_dir.name, "path": str(skill_file), "source": "managed"})
+
+        # Built-in skills
+        if self.builtin_skills and self.builtin_skills.exists():
+            for skill_dir in self.builtin_skills.iterdir():
+                if skill_dir.is_dir():
+                    skill_file = skill_dir / "SKILL.md"
+                    if skill_file.exists() and not any(s["name"] == skill_dir.name for s in skills):
+                        skills.append({"name": skill_dir.name, "path": str(skill_file), "source": "builtin"})
+
+        # Filter by requirements
+        if filter_unavailable:
+            return [s for s in skills if self._check_requirements(self._get_skill_meta(s["name"]))]
+        return skills
+    
+    def load_skill(self, name: str) -> str | None:
+        """
+        Load a skill by name.
+
+        Args:
+            name: Skill name (directory name).
+
+        Returns:
+            Skill content or None if not found.
+        """
+        # Check workspace first (highest priority)
+        workspace_skill = self.workspace_skills / name / "SKILL.md"
+        if workspace_skill.exists():
+            return workspace_skill.read_text(encoding="utf-8")
+
+        # Check managed skills (installed via flowly-hub)
+        managed_skill = self.managed_skills / name / "SKILL.md"
+        if managed_skill.exists():
+            return managed_skill.read_text(encoding="utf-8")
+
+        # Check built-in (lowest priority)
+        if self.builtin_skills:
+            builtin_skill = self.builtin_skills / name / "SKILL.md"
+            if builtin_skill.exists():
+                return builtin_skill.read_text(encoding="utf-8")
+
+        return None
+    
+    def load_skills_for_context(self, skill_names: list[str]) -> str:
+        """
+        Load specific skills for inclusion in agent context.
+        
+        Args:
+            skill_names: List of skill names to load.
+        
+        Returns:
+            Formatted skills content.
+        """
+        parts = []
+        for name in skill_names:
+            content = self.load_skill(name)
+            if content:
+                content = self._strip_frontmatter(content)
+                parts.append(f"### Skill: {name}\n\n{content}")
+        
+        return "\n\n---\n\n".join(parts) if parts else ""
+    
+    def build_skills_summary(self) -> str:
+        """
+        Build a summary of all skills (name, description, path, availability).
+        
+        This is used for progressive loading - the agent can read the full
+        skill content using read_file when needed.
+        
+        Returns:
+            XML-formatted skills summary.
+        """
+        all_skills = self.list_skills(filter_unavailable=False)
+        if not all_skills:
+            return ""
+        
+        def escape_xml(s: str) -> str:
+            return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        
+        lines = ["<skills>"]
+        for s in all_skills:
+            name = escape_xml(s["name"])
+            path = s["path"]
+            desc = escape_xml(self._get_skill_description(s["name"]))
+            skill_meta = self._get_skill_meta(s["name"])
+            available = self._check_requirements(skill_meta)
+            
+            lines.append(f"  <skill available=\"{str(available).lower()}\">")
+            lines.append(f"    <name>{name}</name>")
+            lines.append(f"    <description>{desc}</description>")
+            lines.append(f"    <location>{path}</location>")
+            
+            # Show missing requirements for unavailable skills
+            if not available:
+                missing = self._get_missing_requirements(skill_meta)
+                if missing:
+                    lines.append(f"    <requires>{escape_xml(missing)}</requires>")
+            
+            lines.append(f"  </skill>")
+        lines.append("</skills>")
+        
+        return "\n".join(lines)
+    
+    def _get_missing_requirements(self, skill_meta: dict) -> str:
+        """Get a description of missing requirements."""
+        missing = []
+        requires = skill_meta.get("requires", {})
+        for b in requires.get("bins", []):
+            if not shutil.which(b):
+                missing.append(f"CLI: {b}")
+        for env in requires.get("env", []):
+            if not os.environ.get(env):
+                missing.append(f"ENV: {env}")
+        return ", ".join(missing)
+    
+    def _get_skill_description(self, name: str) -> str:
+        """Get the description of a skill from its frontmatter."""
+        meta = self.get_skill_metadata(name)
+        if meta and meta.get("description"):
+            return meta["description"]
+        return name  # Fallback to skill name
+    
+    def _strip_frontmatter(self, content: str) -> str:
+        """Remove YAML frontmatter from markdown content."""
+        if content.startswith("---"):
+            match = re.match(r"^---\n.*?\n---\n", content, re.DOTALL)
+            if match:
+                return content[match.end():].strip()
+        return content
+    
+    def _parse_flowly_metadata(self, raw: str) -> dict:
+        """Parse flowly metadata JSON from frontmatter."""
+        try:
+            data = json.loads(raw)
+            return data.get("flowly", {}) if isinstance(data, dict) else {}
+        except (json.JSONDecodeError, TypeError):
+            return {}
+    
+    def _check_requirements(self, skill_meta: dict) -> bool:
+        """Check if skill requirements are met (bins, env vars, OS)."""
+        # Check OS compatibility
+        supported_os = skill_meta.get("os", [])
+        if supported_os:
+            current_os = platform.system().lower()
+            os_map = {"windows": "windows", "darwin": "darwin", "linux": "linux"}
+            if os_map.get(current_os, current_os) not in supported_os:
+                return False
+
+        requires = skill_meta.get("requires", {})
+        for b in requires.get("bins", []):
+            if not shutil.which(b):
+                return False
+        for env in requires.get("env", []):
+            if not os.environ.get(env):
+                return False
+        return True
+    
+    def _get_skill_meta(self, name: str) -> dict:
+        """Get flowly metadata for a skill (cached in frontmatter)."""
+        meta = self.get_skill_metadata(name) or {}
+        return self._parse_flowly_metadata(meta.get("metadata", ""))
+    
+    def get_always_skills(self) -> list[str]:
+        """Get skills marked as always=true that meet requirements."""
+        result = []
+        for s in self.list_skills(filter_unavailable=True):
+            meta = self.get_skill_metadata(s["name"]) or {}
+            skill_meta = self._parse_flowly_metadata(meta.get("metadata", ""))
+            if skill_meta.get("always") or meta.get("always"):
+                result.append(s["name"])
+        return result
+    
+    def get_skill_metadata(self, name: str) -> dict | None:
+        """
+        Get metadata from a skill's frontmatter.
+        
+        Args:
+            name: Skill name.
+        
+        Returns:
+            Metadata dict or None.
+        """
+        content = self.load_skill(name)
+        if not content:
+            return None
+        
+        if content.startswith("---"):
+            match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+            if match:
+                # Simple YAML parsing
+                metadata = {}
+                for line in match.group(1).split("\n"):
+                    if ":" in line:
+                        key, value = line.split(":", 1)
+                        metadata[key.strip()] = value.strip().strip('"\'')
+                return metadata
+        
+        return None

flowly_code/agent/subagent.py

@@ -0,0 +1,249 @@
+"""Subagent manager for background task execution."""
+
+import asyncio
+import json
+import uuid
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from flowly_code.bus.events import InboundMessage
+from flowly_code.bus.queue import MessageBus
+from flowly_code.providers.base import LLMProvider
+from flowly_code.agent.tools.registry import ToolRegistry
+from flowly_code.agent.tools.filesystem import ReadFileTool, WriteFileTool, ListDirTool
+from flowly_code.agent.tools.shell import ExecTool
+from flowly_code.agent.tools.web import WebSearchTool, WebFetchTool
+
+
+class SubagentManager:
+    """
+    Manages background subagent execution.
+    
+    Subagents are lightweight agent instances that run in the background
+    to handle specific tasks. They share the same LLM provider but have
+    isolated context and a focused system prompt.
+    """
+    
+    def __init__(
+        self,
+        provider: LLMProvider,
+        workspace: Path,
+        bus: MessageBus,
+        model: str | None = None,
+        brave_api_key: str | None = None,
+        activity_bus: "ActivityBus | None" = None,
+    ):
+        self.provider = provider
+        self.workspace = workspace
+        self.bus = bus
+        self.model = model or provider.get_default_model()
+        self.brave_api_key = brave_api_key
+        self.activity_bus = activity_bus
+        self._running_tasks: dict[str, asyncio.Task[None]] = {}
+
+    def _emit_activity(self, event_type: str, **kwargs: Any) -> None:
+        """Emit an activity event if bus is available and has subscribers."""
+        if not self.activity_bus or not self.activity_bus.has_subscribers:
+            return
+        try:
+            from flowly_code.activity.events import ActivityEvent
+            kwargs.setdefault("agent_name", kwargs.get("subagent_label", "subagent"))
+            self.activity_bus.emit(ActivityEvent(type=event_type, **kwargs))
+        except Exception:
+            pass
+    
+    async def spawn(
+        self,
+        task: str,
+        label: str | None = None,
+        origin_channel: str = "cli",
+        origin_chat_id: str = "direct",
+    ) -> str:
+        """
+        Spawn a subagent to execute a task in the background.
+        
+        Args:
+            task: The task description for the subagent.
+            label: Optional human-readable label for the task.
+            origin_channel: The channel to announce results to.
+            origin_chat_id: The chat ID to announce results to.
+        
+        Returns:
+            Status message indicating the subagent was started.
+        """
+        task_id = str(uuid.uuid4())[:8]
+        display_label = label or task[:30] + ("..." if len(task) > 30 else "")
+        
+        origin = {
+            "channel": origin_channel,
+            "chat_id": origin_chat_id,
+        }
+        
+        # Create background task
+        bg_task = asyncio.create_task(
+            self._run_subagent(task_id, task, display_label, origin)
+        )
+        self._running_tasks[task_id] = bg_task
+        
+        # Cleanup when done
+        bg_task.add_done_callback(lambda _: self._running_tasks.pop(task_id, None))
+        
+        logger.info(f"Spawned subagent [{task_id}]: {display_label}")
+        self._emit_activity("subagent_spawn", subagent_id=task_id, subagent_label=display_label)
+        return f"Subagent [{display_label}] started (id: {task_id}). I'll notify you when it completes."
+    
+    async def _run_subagent(
+        self,
+        task_id: str,
+        task: str,
+        label: str,
+        origin: dict[str, str],
+    ) -> None:
+        """Execute the subagent task and announce the result."""
+        logger.info(f"Subagent [{task_id}] starting task: {label}")
+        
+        try:
+            # Build subagent tools (no message tool, no spawn tool)
+            tools = ToolRegistry()
+            tools.register(ReadFileTool())
+            tools.register(WriteFileTool())
+            tools.register(ListDirTool())
+            tools.register(ExecTool(working_dir=str(self.workspace)))
+            tools.register(WebSearchTool(api_key=self.brave_api_key))
+            tools.register(WebFetchTool())
+            
+            # Build messages with subagent-specific prompt
+            system_prompt = self._build_subagent_prompt(task)
+            messages: list[dict[str, Any]] = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": task},
+            ]
+            
+            # Run agent loop (limited iterations)
+            max_iterations = 15
+            iteration = 0
+            final_result: str | None = None
+            
+            while iteration < max_iterations:
+                iteration += 1
+                
+                response = await self.provider.chat(
+                    messages=messages,
+                    tools=tools.get_definitions(),
+                    model=self.model,
+                )
+                
+                if response.has_tool_calls:
+                    # Add assistant message with tool calls
+                    tool_call_dicts = [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {
+                                "name": tc.name,
+                                "arguments": json.dumps(tc.arguments),
+                            },
+                        }
+                        for tc in response.tool_calls
+                    ]
+                    messages.append({
+                        "role": "assistant",
+                        "content": response.content or "",
+                        "tool_calls": tool_call_dicts,
+                    })
+                    
+                    # Execute tools
+                    for tool_call in response.tool_calls:
+                        logger.debug(f"Subagent [{task_id}] executing: {tool_call.name}")
+                        result = await tools.execute(tool_call.name, tool_call.arguments)
+                        messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "name": tool_call.name,
+                            "content": result,
+                        })
+                else:
+                    final_result = response.content
+                    break
+            
+            if final_result is None:
+                final_result = "Task completed but no final response was generated."
+            
+            logger.info(f"Subagent [{task_id}] completed successfully")
+            self._emit_activity("subagent_end", subagent_id=task_id, subagent_label=label, success=True)
+            await self._announce_result(task_id, label, task, final_result, origin, "ok")
+
+        except Exception as e:
+            error_msg = f"Error: {str(e)}"
+            logger.error(f"Subagent [{task_id}] failed: {e}")
+            self._emit_activity("subagent_end", subagent_id=task_id, subagent_label=label, success=False, error_message=str(e))
+            await self._announce_result(task_id, label, task, error_msg, origin, "error")
+    
+    async def _announce_result(
+        self,
+        task_id: str,
+        label: str,
+        task: str,
+        result: str,
+        origin: dict[str, str],
+        status: str,
+    ) -> None:
+        """Announce the subagent result to the main agent via the message bus."""
+        status_text = "completed successfully" if status == "ok" else "failed"
+        
+        announce_content = f"""[Subagent '{label}' {status_text}]
+
+Task: {task}
+
+Result:
+{result}
+
+Summarize this naturally for the user. Keep it brief (1-2 sentences). Do not mention technical details like "subagent" or task IDs."""
+        
+        # Inject as system message to trigger main agent
+        msg = InboundMessage(
+            channel="system",
+            sender_id="subagent",
+            chat_id=f"{origin['channel']}:{origin['chat_id']}",
+            content=announce_content,
+        )
+        
+        await self.bus.publish_inbound(msg)
+        logger.debug(f"Subagent [{task_id}] announced result to {origin['channel']}:{origin['chat_id']}")
+    
+    def _build_subagent_prompt(self, task: str) -> str:
+        """Build a focused system prompt for the subagent."""
+        return f"""# Subagent
+
+You are a subagent spawned by the main agent to complete a specific task.
+
+## Your Task
+{task}
+
+## Rules
+1. Stay focused - complete only the assigned task, nothing else
+2. Your final response will be reported back to the main agent
+3. Do not initiate conversations or take on side tasks
+4. Be concise but informative in your findings
+
+## What You Can Do
+- Read and write files in the workspace
+- Execute shell commands
+- Search the web and fetch web pages
+- Complete the task thoroughly
+
+## What You Cannot Do
+- Send messages directly to users (no message tool available)
+- Spawn other subagents
+- Access the main agent's conversation history
+
+## Workspace
+Your workspace is at: {self.workspace}
+
+When you have completed the task, provide a clear summary of your findings or actions."""
+    
+    def get_running_count(self) -> int:
+        """Return the number of currently running subagents."""
+        return len(self._running_tasks)

flowly_code/agent/tools/__init__.py

@@ -0,0 +1,6 @@
+"""Agent tools module."""
+
+from flowly_code.agent.tools.base import Tool
+from flowly_code.agent.tools.registry import ToolRegistry
+
+__all__ = ["Tool", "ToolRegistry"]

flowly_code/agent/tools/base.py

@@ -0,0 +1,55 @@
+"""Base class for agent tools."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Tool(ABC):
+    """
+    Abstract base class for agent tools.
+    
+    Tools are capabilities that the agent can use to interact with
+    the environment, such as reading files, executing commands, etc.
+    """
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name used in function calls."""
+        pass
+    
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Description of what the tool does."""
+        pass
+    
+    @property
+    @abstractmethod
+    def parameters(self) -> dict[str, Any]:
+        """JSON Schema for tool parameters."""
+        pass
+    
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> str:
+        """
+        Execute the tool with given parameters.
+        
+        Args:
+            **kwargs: Tool-specific parameters.
+        
+        Returns:
+            String result of the tool execution.
+        """
+        pass
+    
+    def to_schema(self) -> dict[str, Any]:
+        """Convert tool to OpenAI function schema format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            }
+        }