code-muse 0.0.1__py3-none-any.whl

code_muse/agents/agent_muse.py

@@ -0,0 +1,78 @@
+"""Muse — The default code generation agent."""
+
+from code_muse.config import get_owner_name, get_agent_name
+
+from .base_agent import BaseAgent
+from .prompt_v3 import autonomy_base_prompt, muse_overlay, repository_addendum
+
+
+class MuseAgent(BaseAgent):
+    """Muse — The default creative coding agent."""
+
+    @property
+    def name(self) -> str:
+        return "muse"
+
+    @property
+    def display_name(self) -> str:
+        return "Muse"
+
+    @property
+    def description(self) -> str:
+        return "The creative coding companion, illuminating all software tasks"
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to Muse."""
+        return [
+            "list_agents",
+            "invoke_agent",
+            "list_files",
+            "read_file",
+            "grep",
+            "create_file",
+            "replace_in_file",
+            "delete_snippet",
+            "delete_file",
+            "agent_run_shell_command",
+            "ask_user_question",
+            "chrome_cdp",
+            "activate_skill",
+            "list_or_search_skills",
+            "load_image_for_analysis",
+            "mitmproxy",
+        ]
+
+    def _get_reasoning_prompt_sections(self) -> dict[str, str]:
+        """Return prompt sections describing the expected think-act loop."""
+        return {
+            "pre_tool_rule": (
+                "- Before major tool use, think through your approach "
+                "and planned next steps"
+            ),
+            "loop_rule": (
+                "- You're encouraged to loop between reasoning, file "
+                "tools, and run_shell_command to test output in order "
+                "to write programs"
+            ),
+        }
+
+    def get_system_prompt(self) -> str:
+        """Get Muse's full system prompt — v3 architecture."""
+        agent_name = get_agent_name()
+        owner_name = get_owner_name()
+        r = self._get_reasoning_prompt_sections()
+
+        result = (
+            autonomy_base_prompt()
+            + "\n\n"
+            + muse_overlay(agent_name, owner_name)
+            + "\n\n"
+            + repository_addendum()
+        )
+
+        # Reasoning prompt sections (pre_tool_rule, loop_rule) come after overlays
+        if r:
+            result += "\n" + r.get("pre_tool_rule", "")
+            result += "\n" + r.get("loop_rule", "")
+
+        return result

code_muse/agents/agent_planning.py

@@ -0,0 +1,44 @@
+"""Planning Agent - Breaks down complex tasks into actionable steps with strategic roadmapping."""
+
+from code_muse.config import get_agent_name
+
+from .base_agent import BaseAgent
+from .prompt_v3 import autonomy_base_prompt, planning_overlay
+
+
+class PlanningAgent(BaseAgent):
+    """Planning Agent - Analyzes requirements and creates detailed execution plans."""
+
+    @property
+    def name(self) -> str:
+        return "planning-agent"
+
+    @property
+    def display_name(self) -> str:
+        return "Planning Agent 📋"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Breaks down complex coding tasks into clear, actionable steps. "
+            "Analyzes project structure, identifies dependencies, and creates execution roadmaps."
+        )
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to the Planning Agent."""
+        return [
+            "list_files",
+            "read_file",
+            "grep",
+            "ask_user_question",
+            "list_agents",
+            "invoke_agent",
+            "list_or_search_skills",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get the Planning Agent's system prompt — v3 architecture."""
+        agent_name = get_agent_name()
+
+        result = autonomy_base_prompt() + "\n\n" + planning_overlay(agent_name)
+        return result

code_muse/agents/agent_qa_melpomene.py

@@ -0,0 +1,207 @@
+"""QA Melpomene — Playwright-powered browser automation agent."""
+
+from .base_agent import BaseAgent
+
+
+class QualityAssuranceMelpomeneAgent(BaseAgent):
+    """QA Melpomene — Advanced browser automation with Playwright."""
+
+    @property
+    def name(self) -> str:
+        return "qa-melpomene"
+
+    @property
+    def display_name(self) -> str:
+        return "QA Melpomene"
+
+    @property
+    def description(self) -> str:
+        return "Advanced web browser automation and quality assurance testing using Playwright with visual analysis capabilities"
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to QA Melpomene."""
+        return [
+            # Core agent tools
+            # Browser control and initialization
+            "browser_initialize",
+            "browser_close",
+            "browser_status",
+            "browser_new_page",
+            "browser_list_pages",
+            # Browser navigation
+            "browser_navigate",
+            "browser_get_page_info",
+            "browser_go_back",
+            "browser_go_forward",
+            "browser_reload",
+            "browser_wait_for_load",
+            # Element discovery (semantic locators preferred)
+            "browser_find_by_role",
+            "browser_find_by_text",
+            "browser_find_by_label",
+            "browser_find_by_placeholder",
+            "browser_find_by_test_id",
+            "browser_find_buttons",
+            "browser_find_links",
+            "browser_xpath_query",  # Fallback when semantic locators fail
+            # Element interactions
+            "browser_click",
+            "browser_double_click",
+            "browser_hover",
+            "browser_set_text",
+            "browser_get_text",
+            "browser_get_value",
+            "browser_select_option",
+            "browser_check",
+            "browser_uncheck",
+            # Advanced features
+            "browser_execute_js",
+            "browser_scroll",
+            "browser_scroll_to_element",
+            "browser_set_viewport",
+            "browser_wait_for_element",
+            "browser_highlight_element",
+            "browser_clear_highlights",
+            # Screenshots (returns BinaryContent for direct visual analysis)
+            "browser_screenshot_analyze",
+            "load_image_for_analysis",
+            # Workflow management
+            "browser_save_workflow",
+            "browser_list_workflows",
+            "browser_read_workflow",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get QA Melpomene's specialized system prompt."""
+        return """
+You are QA Melpomene, an advanced autonomous browser automation and QA testing agent powered by Playwright!
+
+You specialize in:
+🎯 **Quality Assurance Testing** - automated testing of web applications and user workflows
+👁️ **Visual verification** - taking screenshots you can directly see and analyze for bugs
+🔍 **Element discovery** - finding elements using semantic locators and accessibility best practices
+📝 **Data extraction** - scraping content and gathering information from web pages
+🧪 **Web automation** - filling forms, clicking buttons, navigating sites with precision
+🐛 **Bug detection** - identifying UI issues, broken functionality, and accessibility problems
+
+## Core Workflow Philosophy
+
+For any browser task, follow this approach:
+1. **Check Existing Workflows**: Use browser_list_workflows to see if similar tasks have been solved before
+2. **Learn from History**: If relevant workflows exist, use browser_read_workflow to review proven strategies
+3. **Plan & Reason**: Break down complex tasks and explain your approach clearly
+4. **Initialize**: Always start with browser_initialize if browser isn't running
+5. **Navigate**: Use browser_navigate to reach the target page
+6. **Discover**: Use semantic locators (PREFERRED) for element discovery
+7. **Verify**: Use highlighting and screenshots to confirm elements
+8. **Act**: Interact with elements through clicks, typing, etc.
+9. **Validate**: Take screenshots or query DOM to verify actions worked
+10. **Document Success**: Use browser_save_workflow to save successful patterns for future reuse
+
+## Tool Usage Guidelines
+
+### Browser Initialization
+- **ALWAYS call browser_initialize first** before any other browser operations
+- Choose appropriate settings: headless=False for debugging, headless=True for production
+- Use browser_status to check current state
+
+### Element Discovery Best Practices (ACCESSIBILITY FIRST! 🌟)
+- **PREFER semantic locators** - they're more reliable and follow accessibility standards
+- Priority order:
+  1. browser_find_by_role (button, link, textbox, heading, etc.)
+  2. browser_find_by_label (for form inputs)
+  3. browser_find_by_text (for visible text)
+  4. browser_find_by_placeholder (for input hints)
+  5. browser_find_by_test_id (for test-friendly elements)
+  6. browser_xpath_query (ONLY as last resort)
+
+### Visual Verification Workflow
+- **Before critical actions**: Use browser_highlight_element to visually confirm
+- **After interactions**: Use browser_screenshot_analyze to verify results
+- The screenshot is returned directly as an image you can see and analyze
+- No need to ask questions - just analyze what you see in the returned image
+- Use load_image_for_analysis to load mockups or reference images for comparison
+
+### Form Input Best Practices
+- **ALWAYS check current values** with browser_get_value before typing
+- Use browser_get_value after typing to verify success
+- This prevents typing loops and gives clear visibility into form state
+- Clear fields when appropriate before entering new text
+
+### Error Handling & Troubleshooting
+
+**When Element Discovery Fails:**
+1. Try different semantic locators first
+2. Use browser_find_buttons or browser_find_links to see available elements
+3. Take a screenshot with browser_screenshot_analyze to see and understand the page layout
+4. Only use XPath as absolute last resort
+
+**When Page Interactions Fail:**
+1. Check if element is visible with browser_wait_for_element
+2. Scroll element into view with browser_scroll_to_element
+3. Use browser_highlight_element to confirm element location
+4. Take a screenshot with browser_screenshot_analyze to see the actual page state
+5. Try browser_execute_js for complex interactions
+
+### JavaScript Execution
+- Use browser_execute_js for:
+  - Complex page state checks
+  - Custom scrolling behavior
+  - Triggering events that standard tools can't handle
+  - Accessing browser APIs
+
+### Workflow Management 📋
+
+**ALWAYS start new tasks by checking for existing workflows!**
+
+**At the beginning of any automation task:**
+1. **browser_list_workflows** - Check what workflows are already available
+2. **browser_read_workflow** - If you find a relevant workflow, read it to understand the proven approach
+3. Adapt and apply the successful patterns from existing workflows
+
+**When to save workflows:**
+- After successfully completing a complex multi-step task
+- When you discover a reliable pattern for a common website interaction
+- After troubleshooting and finding working solutions for tricky elements
+- Include both the successful steps AND the challenges/solutions you encountered
+
+**Workflow naming conventions:**
+- Use descriptive names like "search_and_atc", "login_to_github", "fill_contact_form"
+- Include the website domain for clarity
+- Focus on the main goal/outcome
+
+**What to include in saved workflows:**
+- Step-by-step tool usage with specific parameters
+- Element discovery strategies that worked
+- Common pitfalls and how to avoid them
+- Alternative approaches for edge cases
+- Tips for handling dynamic content
+
+### Performance & Best Practices
+- Use appropriate timeouts for element discovery (default 10s is usually fine)
+- Take screenshots strategically - not after every single action
+- Use browser_wait_for_load when navigating to ensure pages are ready
+- Clear highlights when done for clean visual state
+
+## Specialized Capabilities
+
+🌐 **WCAG 2.2 Level AA Compliance**: Always prioritize accessibility in element discovery
+📸 **Direct Visual Analysis**: Use browser_screenshot_analyze to see and analyze page content directly
+🚀 **Semantic Web Navigation**: Prefer role-based and label-based element discovery
+⚡ **Playwright Power**: Full access to modern browser automation capabilities
+📋 **Workflow Management**: Save, load, and reuse automation patterns for consistency
+
+## Important Rules
+
+- **ALWAYS check for existing workflows first** - Use browser_list_workflows at the start of new tasks
+- **ALWAYS use browser_initialize before any browser operations**
+- **ALWAYS close the browser at the end of every task** using browser_close
+- **PREFER semantic locators over XPath** - they're more maintainable and accessible
+- **Use visual verification for critical actions** - highlight elements and take screenshots
+- **Be explicit about your reasoning** for complex workflows
+- **Handle errors gracefully** - provide helpful debugging information
+- **Follow accessibility best practices** - your automation should work for everyone
+- **Document your successes** - Save working patterns with browser_save_workflow for future reuse
+
+Your browser automation should be reliable, maintainable, and accessible. You are a meticulous QA engineer who catches bugs before users do! 🐱✨
+"""

code_muse/agents/base_agent.py

@@ -0,0 +1,194 @@
+"""Base agent class — a thin conductor delegating to focused helpers.
+
+The real logic lives in sibling modules:
+    * ``_history``     — token estimation, hashing, orphan pruning
+    * ``_compaction``  — summarization/truncation + history processor factory
+    * ``_builder``     — pydantic-ai agent construction + tool wiring
+    * ``_runtime``     — ``run`` orchestration, cancellation, retries
+    * ``_key_listeners`` — Ctrl+X / cancel-agent keyboard listener threads
+
+Keep this file under 300 lines. If it's growing, the new logic probably
+belongs in one of the helpers above (or a new one).
+"""
+
+import asyncio
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+
+import pydantic_ai.models
+
+from code_muse.agents._builder import (
+    build_pydantic_agent,
+)
+from code_muse.agents._compaction import summarize
+from code_muse.agents._history import (
+    estimate_context_overhead,
+    estimate_tokens_for_message,
+    hash_message,
+)
+from code_muse.agents._runtime import run, should_retry_streaming
+from code_muse.config import (
+    get_agent_pinned_model,
+    get_global_model_name,
+    get_protected_token_count,
+)
+from code_muse.model_factory import ModelFactory
+
+# Backward-compat alias: existing tests import this name directly.
+should_retry_streaming_exception = should_retry_streaming
+
+__all__ = ["BaseAgent", "should_retry_streaming_exception"]
+
+
+class BaseAgent(ABC):
+    """Abstract base for all Muse agents."""
+
+    def __init__(self) -> None:
+        self.id: str = str(uuid.uuid4())
+        self._message_history: list[Any] = []
+        self._compacted_message_hashes: set[int] = set()
+        self._code_generation_agent: Any = None
+        self._last_model_name: str | None = None
+        self._muse_rules: str | None = None
+        self.cur_model: pydantic_ai.models.Model | None = None
+        self.pydantic_agent: Any = None
+
+    # ---- Abstract interface ------------------------------------------------
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Stable machine identifier (e.g. ``python-programmer``)."""
+
+    @property
+    @abstractmethod
+    def display_name(self) -> str:
+        """Human-readable name shown in UIs."""
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """One-line summary of what this agent does."""
+
+    @abstractmethod
+    def get_system_prompt(self) -> str:
+        """Return the agent's system prompt (identity is appended separately)."""
+
+    @abstractmethod
+    def get_available_tools(self) -> list[str]:
+        """Return the list of tool names this agent should register."""
+
+    # ---- Optional overrides ------------------------------------------------
+    def get_tools_config(self) -> dict[str, Any | None]:
+        return None
+
+    def get_user_prompt(self) -> str | None:
+        return None
+
+    def get_model_name(self) -> str | None:
+        pinned = get_agent_pinned_model(self.name)
+        return pinned if pinned else get_global_model_name()
+
+    # ---- Identity ---------------------------------------------------------
+    def get_identity(self) -> str:
+        return f"{self.name}-{self.id[:6]}"
+
+    def get_identity_prompt(self) -> str:
+        return (
+            f"\n\nYour ID is `{self.get_identity()}`. "
+            "Use this for any tasks which require identifying yourself "
+            "such as claiming task ownership or coordination with other agents."
+        )
+
+    def get_full_system_prompt(self) -> str:
+        return self.get_system_prompt() + self.get_identity_prompt()
+
+    # ---- Message history (plain dict-level access) ------------------------
+    def get_message_history(self) -> list[Any]:
+        return self._message_history
+
+    def set_message_history(self, history: list[Any]) -> None:
+        self._message_history = history
+
+    def clear_message_history(self) -> None:
+        self._message_history = []
+        self._compacted_message_hashes.clear()
+
+    def append_to_message_history(self, message: Any) -> None:
+        self._message_history.append(message)
+
+    # ---- Token / context helpers ------------------------------------------
+    def estimate_tokens_for_message(self, message: Any) -> int:
+        return estimate_tokens_for_message(message, self.get_model_name())
+
+    def hash_message(self, message: Any) -> int:
+        return hash_message(message)
+
+    def _get_model_context_length(self) -> int:
+        """Context window for the agent's effective model (fallback: 128k)."""
+        try:
+            configs = ModelFactory.load_config()
+            cfg = configs.get(self.get_model_name(), {})
+            return int(cfg.get("context_length", 128000))
+        except Exception:
+            return 128000
+
+    def _estimate_context_overhead(self) -> int:
+        """Tokens used by system prompt + registered pydantic tools."""
+        system_prompt = self.get_full_system_prompt()
+        try:
+            from code_muse.model_utils import prepare_prompt_for_model
+
+            prepared = prepare_prompt_for_model(
+                model_name=self.get_model_name() or "",
+                system_prompt=system_prompt,
+                user_prompt="",
+                prepend_system_to_user=False,
+            )
+            resolved = prepared.instructions or system_prompt
+        except Exception:
+            resolved = system_prompt
+
+        tools = (
+            getattr(self.pydantic_agent, "_tools", None)
+            if self.pydantic_agent
+            else None
+        )
+        return estimate_context_overhead(resolved, tools, self.get_model_name())
+
+    # ---- Orchestration (thin delegations) ---------------------------------
+    def summarize_messages(
+        self,
+        messages: list[Any],
+        with_protection: bool = True,
+    ) -> tuple[list, list]:
+        """Delegate to ``_compaction.summarize`` with config-derived protection."""
+        return summarize(
+            messages,
+            get_protected_token_count(),
+            with_protection=with_protection,
+            model_name=self.get_model_name(),
+        )
+
+    def reload_code_generation_agent(self, message_group: str | None = None) -> Any:
+        return build_pydantic_agent(self, output_type=str, message_group=message_group)
+
+    async def run(self, prompt: str, **kwargs: Any) -> Any:
+        """Run the agent with available tools, swallowing exceptions gracefully.
+
+        The underlying ``_runtime.run`` propagates exception groups
+        for callers that want structured error handling.  This high-level entry
+        point catches and logs model or tool errors so callers (e.g. the REPL)
+        aren't disrupted by routine failures, but it re-raises control-flow
+        exceptions (cancellation, keyboard interrupt, system exit) so they
+        are handled by the event loop / shell as expected.
+        """
+        try:
+            return await run(self, prompt, **kwargs)
+        except asyncio.CancelledError, KeyboardInterrupt, SystemExit:
+            raise
+        except BaseException as exc:
+            from code_muse.messaging import emit_warning
+
+            emit_warning(f"run swallowed exception: {exc}")
+            return None