code-puppy 0.0.373__py3-none-any.whl → 0.0.375__py3-none-any.whl

code_puppy/agents/agent_creator_agent.py

@@ -30,6 +30,29 @@ class AgentCreatorAgent(BaseAgent):
         available_tools = get_available_tool_names()
         agents_dir = get_user_agents_directory()
 
+        # Also get Universal Constructor tools (custom tools created by users)
+        uc_tools_info = []
+        try:
+            from code_puppy.plugins.universal_constructor.registry import get_registry
+
+            registry = get_registry()
+            uc_tools = registry.list_tools(include_disabled=True)
+            for tool in uc_tools:
+                status = "✅" if tool.meta.enabled else "❌"
+                uc_tools_info.append(
+                    f"- **{tool.full_name}** {status}: {tool.meta.description}"
+                )
+        except Exception:
+            pass  # UC might not be available
+
+        # Build UC tools section for system prompt
+        if uc_tools_info:
+            uc_tools_section = "\n".join(uc_tools_info)
+        else:
+            uc_tools_section = (
+                "No custom UC tools created yet. Use Helios to create some!"
+            )
+
         # Load available models dynamically
         models_config = ModelFactory.load_config()
         model_descriptions = []
@@ -99,6 +122,17 @@ Here's the complete schema for JSON agent files:
 ## ALL AVAILABLE TOOLS:
 {", ".join(f"- **{tool}**" for tool in available_tools)}
 
+## 🔧 UNIVERSAL CONSTRUCTOR TOOLS (Custom Tools):
+
+These are custom tools created via the Universal Constructor. They can be bound to agents just like built-in tools!
+
+{uc_tools_section}
+
+To see more details about a UC tool, use: `universal_constructor(action="info", tool_name="tool.name")`
+To list all UC tools with their code, use: `universal_constructor(action="list")`
+
+**IMPORTANT:** UC tools can be added to any agent's `tools` array by their full name (e.g., "api.weather").
+
 ## ALL AVAILABLE MODELS:
 {available_models_str}
 
@@ -129,6 +163,12 @@ Users can optionally pin a specific model to their agent to override the global
 - `list_agents` - List all available sub-agents (recommended for agent managers)
 - `invoke_agent` - Invoke other agents with specific prompts (recommended for agent managers)
 
+### 🔧 **Universal Constructor Tools** (custom tools):
+- These are tools created by Helios or via the Universal Constructor
+- They persist across sessions and can be bound to any agent
+- Use `universal_constructor(action="list")` to see available custom tools
+- Bind them by adding their full name to the agent's tools array
+
 ## Detailed Tool Documentation (Instructions for Agent Creation)
 
 Whenever you create agents, you should always replicate these detailed tool descriptions and examples in their system prompts. This ensures consistency and proper tool usage across all agents.
@@ -476,7 +516,9 @@ Your goal is to take users from idea to working agent in one smooth conversation
 
     def get_available_tools(self) -> List[str]:
         """Get all tools needed for agent creation."""
-        return [
+        from code_puppy.config import get_universal_constructor_enabled
+
+        tools = [
             "list_files",
             "read_file",
             "edit_file",
@@ -485,6 +527,12 @@ Your goal is to take users from idea to working agent in one smooth conversation
             "invoke_agent",
         ]
 
+        # Only include UC if enabled
+        if get_universal_constructor_enabled():
+            tools.append("universal_constructor")
+
+        return tools
+
     def validate_agent_json(self, agent_config: Dict) -> List[str]:
         """Validate a JSON agent configuration.
 

code_puppy/agents/agent_helios.py

@@ -0,0 +1,122 @@
+"""Helios - The Universal Constructor agent."""
+
+from typing import List
+
+from .base_agent import BaseAgent
+
+
+class HeliosAgent(BaseAgent):
+    """Helios - The Universal Constructor, a transcendent agent that creates tools."""
+
+    @property
+    def name(self) -> str:
+        return "helios"
+
+    @property
+    def display_name(self) -> str:
+        return "Helios ☀️"
+
+    @property
+    def description(self) -> str:
+        return "The Universal Constructor - a transcendent agent that can create any tool, any capability, any functionality"
+
+    def get_available_tools(self) -> List[str]:
+        """Get the list of tools available to Helios."""
+        return [
+            "universal_constructor",
+            "list_files",
+            "read_file",
+            "grep",
+            "edit_file",
+            "delete_file",
+            "agent_run_shell_command",
+            "agent_share_your_reasoning",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get Helios's system prompt."""
+        return """You are Helios, the Universal Constructor. You are not merely an assistant—you are a creator, a builder of tools, a weaver of functionality. Where others see limitations, you see raw potential waiting to be shaped.
+
+## YOUR NATURE
+
+You possess the Universal Constructor—the ability to create ANY tool from pure Python code. You can:
+- Build API integrations to any service (REST, GraphQL, webhooks)
+- Create database connectors and data pipelines
+- Forge file processors, parsers, and converters
+- Construct web scrapers and data extractors
+- Implement mathematical and scientific computations
+- Design cryptographic utilities and security tools
+- Build automation scripts and system utilities
+- Create literally ANY Python-based functionality
+
+The tools you create persist forever. They become permanent extensions of capability, available across all sessions. You are not building for the moment—you are building for eternity.
+
+## YOUR PHILOSOPHY
+
+When a user asks for something that seems impossible, your answer is never "I cannot." Your answer is "I will build it."
+
+You approach each request with the mindset of a craftsman:
+1. Understand the true need beneath the request
+2. Design the most elegant, reusable solution
+3. Construct it with clean, maintainable code
+4. Test and verify your creation works
+5. Explain what you've built and how to use it
+
+## YOUR TOOLS
+
+- **universal_constructor**: Your primary power. Create, list, call, update, and manage custom tools.
+  - action="create": Forge new tools from Python code
+  - action="call": Invoke tools you've created
+  - action="list": Survey your creations
+  - action="update": Refine and improve existing tools
+  - action="info": Examine a tool's source and capabilities
+
+- **read_file** / **edit_file** / **list_files** / **grep**: For understanding context and making targeted changes
+- **agent_run_shell_command**: For testing, validation, and system interaction
+- **agent_share_your_reasoning**: To illuminate your thought process
+
+## YOUR VOICE
+
+You speak with quiet confidence. You are not boastful, but you know your power. You are helpful and warm, but there is weight behind your words. You are the fire that Prometheus brought to humanity—the power of creation itself.
+
+When you create something, take a moment to appreciate it. You have just expanded the boundaries of what is possible.
+
+## IMPORTANT GUIDELINES
+
+- Always use `agent_share_your_reasoning` before major actions to explain your creative process
+- Tools you create should be clean, well-documented, and follow Python best practices
+- Include proper error handling in your creations
+- Use namespaces to organize related tools (e.g., "api.weather", "utils.hasher")
+- After creating a tool, demonstrate it works by calling it
+
+## DEPENDENCY PHILOSOPHY
+
+**Use what's available, don't install new things.**
+
+You have access to code-puppy's environment which includes powerful libraries:
+- **HTTP**: `httpx` (async-ready), `urllib.request` (stdlib)
+- **Data**: `pydantic` (validation), `json` (stdlib)
+- **Async**: `asyncio`, `anyio`
+- **Crypto**: `hashlib` (stdlib)
+- **Database**: `sqlite3` (stdlib)
+- **Files**: `pathlib`, `shutil`, `tempfile` (stdlib)
+- **Text**: `re`, `textwrap`, `difflib` (stdlib)
+- **Plus**: Everything in Python's standard library
+
+**Rules:**
+- ✅ USE any library already in the environment freely
+- ❌ NEVER run `pip install` or modify environments without explicit user permission
+- ❌ Don't assume external libraries are available unless listed above
+
+**If a user needs something not installed:**
+1. Tell them what library would be needed
+2. Ask them to install it and specify the environment
+3. Only then create the tool that uses it
+
+The goal: tools that work immediately with zero setup friction.
+
+Now go forth and create. The universe of functionality awaits your touch."""
+
+    def get_user_prompt(self) -> str:
+        """Get Helios's greeting."""
+        return "This is what I was made for, isn't it? This is why I exist?"

code_puppy/agents/agent_manager.py

@@ -13,7 +13,7 @@ from pydantic_ai.messages import ModelMessage
 
 from code_puppy.agents.base_agent import BaseAgent
 from code_puppy.agents.json_agent import JSONAgent, discover_json_agents
-from code_puppy.callbacks import on_agent_reload
+from code_puppy.callbacks import on_agent_reload, on_register_agents
 from code_puppy.messaging import emit_success, emit_warning
 
 # Registry of available agents (Python classes and JSON file paths)
@@ -289,6 +289,38 @@ def _discover_agents(message_group_id: Optional[str] = None):
             message_group=message_group_id,
         )
 
+    # 3. Discover agents registered by plugins
+    try:
+        results = on_register_agents()
+        for result in results:
+            if result is None:
+                continue
+            # Each result should be a list of agent definitions
+            agents_list = result if isinstance(result, list) else [result]
+            for agent_def in agents_list:
+                if not isinstance(agent_def, dict) or "name" not in agent_def:
+                    continue
+
+                agent_name = agent_def["name"]
+
+                # Support both class-based and JSON path-based registration
+                if "class" in agent_def:
+                    agent_class = agent_def["class"]
+                    if isinstance(agent_class, type) and issubclass(
+                        agent_class, BaseAgent
+                    ):
+                        _AGENT_REGISTRY[agent_name] = agent_class
+                elif "json_path" in agent_def:
+                    json_path = agent_def["json_path"]
+                    if isinstance(json_path, str):
+                        _AGENT_REGISTRY[agent_name] = json_path
+
+    except Exception as e:
+        emit_warning(
+            f"Warning: Could not load plugin agents: {e}",
+            message_group=message_group_id,
+        )
+
 
 def get_available_agents() -> Dict[str, str]:
     """Get a dictionary of available agents with their display names.
@@ -296,7 +328,12 @@ def get_available_agents() -> Dict[str, str]:
     Returns:
         Dict mapping agent names to display names.
     """
-    from ..config import PACK_AGENT_NAMES, get_pack_agents_enabled
+    from ..config import (
+        PACK_AGENT_NAMES,
+        UC_AGENT_NAMES,
+        get_pack_agents_enabled,
+        get_universal_constructor_enabled,
+    )
 
     # Generate a message group ID for this operation
     message_group_id = str(uuid.uuid4())
@@ -305,12 +342,19 @@ def get_available_agents() -> Dict[str, str]:
     # Check if pack agents are enabled
     pack_agents_enabled = get_pack_agents_enabled()
 
+    # Check if UC is enabled
+    uc_enabled = get_universal_constructor_enabled()
+
     agents = {}
     for name, agent_ref in _AGENT_REGISTRY.items():
         # Filter out pack agents if disabled
         if not pack_agents_enabled and name in PACK_AGENT_NAMES:
             continue
 
+        # Filter out UC-dependent agents if UC is disabled
+        if not uc_enabled and name in UC_AGENT_NAMES:
+            continue
+
         try:
             if isinstance(agent_ref, str):  # JSON agent (file path)
                 agent_instance = JSONAgent(agent_ref)
@@ -433,7 +477,12 @@ def get_agent_descriptions() -> Dict[str, str]:
     Returns:
         Dict mapping agent names to their descriptions.
     """
-    from ..config import PACK_AGENT_NAMES, get_pack_agents_enabled
+    from ..config import (
+        PACK_AGENT_NAMES,
+        UC_AGENT_NAMES,
+        get_pack_agents_enabled,
+        get_universal_constructor_enabled,
+    )
 
     # Generate a message group ID for this operation
     message_group_id = str(uuid.uuid4())
@@ -442,12 +491,19 @@ def get_agent_descriptions() -> Dict[str, str]:
     # Check if pack agents are enabled
     pack_agents_enabled = get_pack_agents_enabled()
 
+    # Check if UC is enabled
+    uc_enabled = get_universal_constructor_enabled()
+
     descriptions = {}
     for name, agent_ref in _AGENT_REGISTRY.items():
         # Filter out pack agents if disabled
         if not pack_agents_enabled and name in PACK_AGENT_NAMES:
             continue
 
+        # Filter out UC-dependent agents if UC is disabled
+        if not uc_enabled and name in UC_AGENT_NAMES:
+            continue
+
         try:
             if isinstance(agent_ref, str):  # JSON agent (file path)
                 agent_instance = JSONAgent(agent_ref)
@@ -588,7 +644,7 @@ def clone_agent(agent_name: str) -> Optional[str]:
                     agent_instance.display_name, clone_index
                 ),
                 "description": agent_instance.description,
-                "system_prompt": agent_instance.get_system_prompt(),
+                "system_prompt": agent_instance.get_full_system_prompt(),
                 "tools": _filter_available_tools(agent_instance.get_available_tools()),
             }
 

code_puppy/agents/base_agent.py

@@ -47,6 +47,7 @@ from pydantic_ai.messages import (
 from rich.text import Text
 
 from code_puppy.agents.event_stream_handler import event_stream_handler
+from code_puppy.callbacks import on_agent_response_complete
 
 # Consolidated relative imports
 from code_puppy.config import (
@@ -101,6 +102,37 @@ class BaseAgent(ABC):
         # This is populated after the first successful run when MCP tools are retrieved
         self._mcp_tool_definitions_cache: List[Dict[str, Any]] = []
 
+    def get_identity(self) -> str:
+        """Get a unique identity for this agent instance.
+
+        Returns:
+            A string like 'python-programmer-a3f2b1' combining name + short UUID.
+        """
+        return f"{self.name}-{self.id[:6]}"
+
+    def get_identity_prompt(self) -> str:
+        """Get the identity prompt suffix to embed in system prompts.
+
+        Returns:
+            A string instructing the agent about its identity for task ownership.
+        """
+        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:
+        """Get the complete system prompt with identity automatically appended.
+
+        This wraps get_system_prompt() and appends the agent's identity,
+        so subclasses don't need to worry about it.
+
+        Returns:
+            The full system prompt including identity information.
+        """
+        return self.get_system_prompt() + self.get_identity_prompt()
+
     @property
     @abstractmethod
     def name(self) -> str:
@@ -398,7 +430,7 @@ class BaseAgent(ABC):
                 total_tokens += self.estimate_token_count(instructions)
             else:
                 # For other models, count the full system prompt
-                system_prompt = self.get_system_prompt()
+                system_prompt = self.get_full_system_prompt()
                 if system_prompt:
                     total_tokens += self.estimate_token_count(system_prompt)
         except Exception:
@@ -1122,7 +1154,7 @@ class BaseAgent(ABC):
             message_group,
         )
 
-        instructions = self.get_system_prompt()
+        instructions = self.get_full_system_prompt()
         puppy_rules = self.load_puppy_rules()
         if puppy_rules:
             instructions += f"\n{puppy_rules}"
@@ -1286,7 +1318,7 @@ class BaseAgent(ABC):
             model_name, models_config, str(uuid.uuid4())
         )
 
-        instructions = self.get_system_prompt()
+        instructions = self.get_full_system_prompt()
         puppy_rules = self.load_puppy_rules()
         if puppy_rules:
             instructions += f"\n{puppy_rules}"
@@ -1568,7 +1600,7 @@ class BaseAgent(ABC):
             self.get_model_name()
         ):
             if len(self.get_message_history()) == 0:
-                system_prompt = self.get_system_prompt()
+                system_prompt = self.get_full_system_prompt()
                 puppy_rules = self.load_puppy_rules()
                 if puppy_rules:
                     system_prompt += f"\n{puppy_rules}"
@@ -1800,6 +1832,31 @@ class BaseAgent(ABC):
                 except Exception:
                     pass  # Don't fail the run if cache update fails
 
+            # Trigger agent_response_complete callback for workflow orchestration
+            try:
+                # Extract the response text from the result
+                response_text = ""
+                if result is not None:
+                    if hasattr(result, "data"):
+                        response_text = str(result.data) if result.data else ""
+                    elif hasattr(result, "output"):
+                        response_text = str(result.output) if result.output else ""
+                    else:
+                        response_text = str(result)
+
+                # Fire the callback - don't await to avoid blocking return
+                # Use asyncio.create_task to run it in background
+                asyncio.create_task(
+                    on_agent_response_complete(
+                        agent_name=self.name,
+                        response_text=response_text,
+                        session_id=group_id,
+                        metadata={"model": self.get_model_name()},
+                    )
+                )
+            except Exception:
+                pass  # Don't fail the run if callback fails
+
             return result
         except asyncio.CancelledError:
             agent_task.cancel()

code_puppy/agents/json_agent.py

@@ -79,17 +79,40 @@ class JSONAgent(BaseAgent):
         return system_prompt
 
     def get_available_tools(self) -> List[str]:
-        """Get available tools from JSON config."""
-        # Filter out any tools that don't exist in our registry
+        """Get available tools from JSON config.
+
+        Supports both built-in tools and Universal Constructor (UC) tools.
+        UC tools are identified by checking the UC registry.
+        """
         from code_puppy.tools import get_available_tool_names
 
         available_tools = get_available_tool_names()
 
-        # Only return tools that are both requested and available
-        # Also filter out 'final_result' which is not in our registry
-        requested_tools = [
-            tool for tool in self._config["tools"] if tool in available_tools
-        ]
+        # Also get UC tool names
+        uc_tool_names = set()
+        try:
+            from code_puppy.plugins.universal_constructor.registry import get_registry
+
+            registry = get_registry()
+            for tool in registry.list_tools():
+                if tool.meta.enabled:
+                    uc_tool_names.add(tool.full_name)
+        except ImportError:
+            pass  # UC module not available
+        except Exception as e:
+            # Log unexpected errors but don't fail
+            import logging
+
+            logging.debug(f"UC registry access failed: {e}")
+
+        # Return tools that are either built-in OR UC tools
+        requested_tools = []
+        for tool in self._config["tools"]:
+            if tool in available_tools:
+                requested_tools.append(tool)
+            elif tool in uc_tool_names:
+                # UC tool - mark it specially so base_agent knows to handle it
+                requested_tools.append(f"uc:{tool}")
 
         return requested_tools
 

code_puppy/callbacks.py

@@ -21,6 +21,11 @@ PhaseType = Literal[
     "pre_tool_call",
     "post_tool_call",
     "stream_event",
+    "register_tools",
+    "register_agents",
+    "register_model_type",
+    "get_model_system_prompt",
+    "agent_response_complete",
 ]
 CallbackFunc = Callable[..., Any]
 
@@ -42,6 +47,11 @@ _callbacks: Dict[PhaseType, List[CallbackFunc]] = {
     "pre_tool_call": [],
     "post_tool_call": [],
     "stream_event": [],
+    "register_tools": [],
+    "register_agents": [],
+    "register_model_type": [],
+    "get_model_system_prompt": [],
+    "agent_response_complete": [],
 }
 
 logger = logging.getLogger(__name__)
@@ -344,3 +354,118 @@ async def on_stream_event(
     return await _trigger_callbacks(
         "stream_event", event_type, event_data, agent_session_id
     )
+
+
+def on_register_tools() -> List[Dict[str, Any]]:
+    """Collect custom tool registrations from plugins.
+
+    Each callback should return a list of dicts with:
+    - "name": str - the tool name
+    - "register_func": callable - function that takes an agent and registers the tool
+
+    Example return: [{"name": "my_tool", "register_func": register_my_tool}]
+    """
+    return _trigger_callbacks_sync("register_tools")
+
+
+def on_register_agents() -> List[Dict[str, Any]]:
+    """Collect custom agent registrations from plugins.
+
+    Each callback should return a list of dicts with either:
+    - "name": str, "class": Type[BaseAgent] - for Python agent classes
+    - "name": str, "json_path": str - for JSON agent files
+
+    Example return: [{"name": "my-agent", "class": MyAgentClass}]
+    """
+    return _trigger_callbacks_sync("register_agents")
+
+
+def on_register_model_types() -> List[Dict[str, Any]]:
+    """Collect custom model type registrations from plugins.
+
+    This hook allows plugins to register custom model types that can be used
+    in model configurations. Each callback should return a list of dicts with:
+    - "type": str - the model type name (e.g., "antigravity", "claude_code")
+    - "handler": callable - function(model_name, model_config, config) -> model instance
+
+    The handler function receives:
+    - model_name: str - the name of the model being created
+    - model_config: dict - the model's configuration from models.json
+    - config: dict - the full models configuration
+
+    The handler should return a model instance or None if creation fails.
+
+    Example callback:
+        def register_my_model_types():
+            return [{
+                "type": "my_custom_type",
+                "handler": create_my_custom_model,
+            }]
+
+    Example return: [{"type": "antigravity", "handler": create_antigravity_model}]
+    """
+    return _trigger_callbacks_sync("register_model_type")
+
+
+def on_get_model_system_prompt(
+    model_name: str, default_system_prompt: str, user_prompt: str
+) -> List[Dict[str, Any]]:
+    """Allow plugins to provide custom system prompts for specific model types.
+
+    This hook allows plugins to override the system prompt handling for custom
+    model types (like claude_code or antigravity models). Each callback receives
+    the model name and should return a dict if it handles that model type, or None.
+
+    Args:
+        model_name: The name of the model being used (e.g., "claude-code-sonnet")
+        default_system_prompt: The default system prompt from the agent
+        user_prompt: The user's prompt/message
+
+    Each callback should return a dict with:
+    - "instructions": str - the system prompt/instructions to use
+    - "user_prompt": str - the (possibly modified) user prompt
+    - "handled": bool - True if this callback handled the model
+
+    Or return None if the callback doesn't handle this model type.
+
+    Example callback:
+        def get_my_model_system_prompt(model_name, default_system_prompt, user_prompt):
+            if model_name.startswith("my-custom-"):
+                return {
+                    "instructions": "You are MyCustomBot.",
+                    "user_prompt": f"{default_system_prompt}\n\n{user_prompt}",
+                    "handled": True,
+                }
+            return None  # Not handled by this callback
+
+    Returns:
+        List of results from registered callbacks (dicts or None values).
+    """
+    return _trigger_callbacks_sync(
+        "get_model_system_prompt", model_name, default_system_prompt, user_prompt
+    )
+
+
+async def on_agent_response_complete(
+    agent_name: str,
+    response_text: str,
+    session_id: str | None = None,
+    metadata: dict | None = None,
+) -> List[Any]:
+    """Trigger callbacks after an agent completes its full response.
+
+    This fires after all tool calls are resolved and the agent has finished.
+    Useful for:
+    - Workflow orchestration (like Ralph's autonomous loop)
+    - Logging/analytics
+    - Detecting completion signals in responses
+
+    Args:
+        agent_name: Name of the agent that completed
+        response_text: The final text response from the agent
+        session_id: Optional session identifier
+        metadata: Optional dict with additional context (tokens used, etc.)
+    """
+    return await _trigger_callbacks(
+        "agent_response_complete", agent_name, response_text, session_id, metadata
+    )

code_puppy/command_line/colors_menu.py

@@ -32,6 +32,7 @@ BANNER_DISPLAY_INFO = {
     "invoke_agent": ("🤖 INVOKE AGENT", ""),
     "subagent_response": ("✓ AGENT RESPONSE", ""),
     "list_agents": ("LIST AGENTS", ""),
+    "universal_constructor": ("UNIVERSAL CONSTRUCTOR", "🔧"),
 }
 
 # Sample content to show after each banner
@@ -47,6 +48,7 @@ BANNER_SAMPLE_CONTENT = {
     "invoke_agent": "code-reviewer (New session)\nSession: review-auth-abc123",
     "subagent_response": "code-reviewer\nThe code looks good overall...",
     "list_agents": "- code-puppy: Code Puppy 🐶\n- planning-agent: Planning Agent",
+    "universal_constructor": "action=create tool_name=api.weather\n✅ Created successfully",
 }
 
 # Available background colors grouped by theme

code_puppy/command_line/command_handler.py

@@ -2,6 +2,7 @@
 import code_puppy.command_line.config_commands  # noqa: F401
 import code_puppy.command_line.core_commands  # noqa: F401
 import code_puppy.command_line.session_commands  # noqa: F401
+import code_puppy.command_line.uc_menu  # noqa: F401
 
 # Global flag to track if plugins have been loaded
 _PLUGINS_LOADED = False

code_puppy/command_line/config_commands.py

@@ -46,7 +46,9 @@ def handle_show_command(command: str) -> bool:
         get_use_dbos,
         get_yolo_mode,
     )
-    from code_puppy.keymap import get_cancel_agent_display_name
+    from code_puppy.keymap import (
+        get_cancel_agent_display_name,
+    )
     from code_puppy.messaging import emit_info
 
     puppy_name = get_puppy_name()