dulus 0.2.0__py3-none-any.whl

multi_agent/tools.py

@@ -0,0 +1,393 @@
+"""Multi-agent tool registrations.
+
+Registers the following tools into the central tool_registry:
+  Agent            — spawn a sub-agent (always background)
+  SendMessage      — send a message to a named background agent
+  CheckAgentResult — check status/result of a background agent
+  ListAgentTasks   — list all active/finished agent tasks
+  ListAgentTypes   — list available agent type definitions
+"""
+from __future__ import annotations
+
+from tool_registry import ToolDef, register_tool
+from .subagent import SubAgentManager, get_agent_definition, load_agent_definitions
+
+
+# ── Singleton manager ──────────────────────────────────────────────────────
+
+_agent_manager: SubAgentManager | None = None
+
+
+def get_agent_manager() -> SubAgentManager:
+    """Return (and lazily create) the process-wide SubAgentManager."""
+    global _agent_manager
+    if _agent_manager is None:
+        _agent_manager = SubAgentManager()
+    return _agent_manager
+
+
+# ── Tool implementations ───────────────────────────────────────────────────
+
+def _agent_tool(params: dict, config: dict) -> str:
+    """Spawn a sub-agent.
+
+    Reads from config:
+      _system_prompt  — injected by agent.py run(), used as base system prompt
+      _depth          — current nesting depth (prevents infinite recursion)
+    """
+    mgr = get_agent_manager()
+
+    prompt = params["prompt"]
+    # Sub-agents ALWAYS run in background. A sub must never block the main
+    # agent's stream — `wait` is no longer accepted from the model.
+    wait = False
+    isolation = params.get("isolation", "")
+    name = params.get("name", "")
+    model_override = params.get("model", "")
+    subagent_type = params.get("subagent_type", "")
+
+    system_prompt = config.get("_system_prompt", "You are a helpful assistant.")
+    depth = config.get("_depth", 0)
+
+    # Strip private keys before passing to sub-agent, but preserve the hooks
+    # that AskMainAgentQuestion needs to reach back into the main agent.
+    eff_config = {k: v for k, v in config.items() if not k.startswith("_")}
+    for k in ("_run_query_callback", "_state"):
+        if k in config:
+            eff_config[k] = config[k]
+    if model_override:
+        eff_config["model"] = model_override
+
+    # Resolve agent definition
+    agent_def = None
+    if subagent_type:
+        agent_def = get_agent_definition(subagent_type)
+        if agent_def is None:
+            return (
+                f"Error: unknown subagent_type '{subagent_type}'. "
+                "Use ListAgentTypes to see available types."
+            )
+
+    task = mgr.spawn(
+        prompt, eff_config, system_prompt,
+        depth=depth,
+        agent_def=agent_def,
+        isolation=isolation,
+        name=name,
+    )
+
+    if task.status == "failed":
+        return f"Error spawning agent: {task.result}"
+
+    if wait:
+        mgr.wait(task.id, timeout=300)
+        result = task.result or f"(no output — status: {task.status})"
+        header = f"[Agent: {task.name}"
+        if subagent_type:
+            header += f" ({subagent_type})"
+        if task.worktree_branch:
+            header += f", branch: {task.worktree_branch}"
+        header += "]"
+        return f"{header}\n\n{result}"
+    else:
+        info_parts = [f"Task ID: {task.id}", f"Name: {task.name}", f"Status: {task.status}"]
+        if subagent_type:
+            info_parts.append(f"Type: {subagent_type}")
+        if task.worktree_branch:
+            info_parts.append(f"Worktree branch: {task.worktree_branch}")
+        info_parts.append("Use CheckAgentResult or SendMessage to interact with this agent.")
+        return "\n".join(info_parts)
+
+
+def _send_message(params: dict, config: dict) -> str:
+    mgr = get_agent_manager()
+    target = params["to"]
+    message = params["message"]
+    ok = mgr.send_message(target, message)
+    if ok:
+        return f"Message queued for agent '{target}'. It will be processed after current work completes."
+    task_id = mgr._by_name.get(target, target)
+    task = mgr.tasks.get(task_id)
+    if task is None:
+        return f"Error: no agent found with id or name '{target}'"
+    return f"Error: agent '{target}' is not running (status: {task.status}). Cannot send message."
+
+
+def _check_agent_result(params: dict, config: dict) -> str:
+    mgr = get_agent_manager()
+    task_id = params["task_id"]
+    task = mgr.tasks.get(task_id)
+    if task is None:
+        return f"Error: no task with id '{task_id}'"
+    lines = [f"Status: {task.status}", f"Name: {task.name}"]
+    if task.worktree_branch:
+        lines.append(f"Worktree branch: {task.worktree_branch}")
+    if task.result:
+        lines.append(f"\nResult:\n{task.result}")
+    return "\n".join(lines)
+
+
+def _list_agent_tasks(params: dict, config: dict) -> str:
+    mgr = get_agent_manager()
+    tasks = mgr.list_tasks()
+    if not tasks:
+        return "No sub-agent tasks."
+    lines = ["ID           | Name     | Status    | Worktree branch | Prompt"]
+    lines.append("-------------|----------|-----------|-----------------|------")
+    for t in tasks:
+        prompt_short = t.prompt[:50] + ("..." if len(t.prompt) > 50 else "")
+        wt = t.worktree_branch[:15] if t.worktree_branch else "-"
+        lines.append(f"{t.id} | {t.name[:8]:8s} | {t.status:9s} | {wt:15s} | {prompt_short}")
+    return "\n".join(lines)
+
+
+def _ask_main_agent_question(params: dict, config: dict) -> str:
+    """Pause a sub-agent and ask the main agent a question.
+
+    The sub-agent blocks on a threading.Event in its current turn (preserving
+    full context). The main agent receives a system message naming the
+    sub-agent and the question; it replies using SendMessage(to=<name>, ...).
+    """
+    import threading as _threading
+
+    question = params.get("question", "").strip()
+    if not question:
+        return "Error: 'question' parameter is required."
+
+    task_id = config.get("_subagent_task_id")
+    if not task_id:
+        return (
+            "Error: AskMainAgentQuestion can only be called from within a "
+            "sub-agent. If you ARE the main agent, use AskUserQuestion instead."
+        )
+
+    mgr = get_agent_manager()
+    task = mgr.tasks.get(task_id)
+    if task is None:
+        return f"Error: sub-agent task '{task_id}' not found."
+
+    run_query_cb = config.get("_run_query_callback")
+    main_state = config.get("_state")
+    if run_query_cb is None or main_state is None:
+        return (
+            "Error: main-agent hooks unavailable. AskMainAgentQuestion requires "
+            "the sub-agent to have been spawned from an active REPL session."
+        )
+
+    # Register the pending question on the task.
+    event = _threading.Event()
+    holder: list[str] = []
+    task._pending_question = {
+        "question": question,
+        "event":    event,
+        "result":   holder,
+    }
+
+    # Inject a system message into the main agent's state and trigger a turn.
+    addr = task.name or task.id
+    sys_msg = (
+        f"(System Event): Sub-agent '{addr}' is paused and asking you a question:\n\n"
+        f"    {question}\n\n"
+        f"Reply by calling SendMessage(to='{addr}', message='<your answer>'). "
+        f"The sub-agent is holding its full context and will resume the same "
+        f"turn once you respond."
+    )
+    try:
+        main_state.messages.append({"role": "system", "content": sys_msg})
+    except Exception:
+        pass
+    try:
+        run_query_cb(sys_msg)
+    except Exception as e:
+        task._pending_question = None
+        return f"Error: failed to notify main agent: {e}"
+
+    # Block the sub-agent until the main replies (or we hit the timeout).
+    got = event.wait(timeout=600)
+    task._pending_question = None
+    if not got:
+        return "(no answer — timeout after 600s waiting for main agent)"
+    return holder[0] if holder else "(no answer)"
+
+
+def _list_agent_types(params: dict, config: dict) -> str:
+    defs = load_agent_definitions()
+    if not defs:
+        return "No agent types available."
+    lines = ["Available agent types:", ""]
+    for aname, d in sorted(defs.items()):
+        model_info = f"  model: {d.model}" if d.model else ""
+        tools_info = f"  tools: {', '.join(d.tools)}" if d.tools else ""
+        lines.append(f"  {aname:20s}  [{d.source:8s}]  {d.description}")
+        if model_info:
+            lines.append(f"                           {model_info}")
+        if tools_info:
+            lines.append(f"                           {tools_info}")
+    lines.append("")
+    lines.append(
+        "Create custom agents: place .md files in ~/.dulus/agents/ or .dulus/agents/"
+    )
+    return "\n".join(lines)
+
+
+# ── Tool registrations ─────────────────────────────────────────────────────
+
+register_tool(ToolDef(
+    name="Agent",
+    schema={
+        "name": "Agent",
+        "description": (
+            "Spawn a sub-agent to handle a task autonomously. The sub-agent runs in a "
+            "separate thread with its own conversation history. Supports specialized agent "
+            "types (coder, reviewer, researcher, tester, or custom from .dulus/agents/), "
+            "isolated git worktrees for parallel work, and background execution.\n\n"
+            "When using isolation='worktree', the agent gets its own git branch and "
+            "working copy — ideal for parallel coding tasks that shouldn't interfere."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": "Task description for the sub-agent",
+                },
+                "subagent_type": {
+                    "type": "string",
+                    "description": (
+                        "Specialized agent type: 'general-purpose', 'coder', 'reviewer', "
+                        "'researcher', 'tester', or any custom type. "
+                        "Use ListAgentTypes to see all available types."
+                    ),
+                },
+                "name": {
+                    "type": "string",
+                    "description": (
+                        "Human-readable name for this agent instance. "
+                        "Makes it addressable via SendMessage while running in background."
+                    ),
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model override for this specific agent (optional)",
+                },
+                "isolation": {
+                    "type": "string",
+                    "enum": ["worktree"],
+                    "description": (
+                        "'worktree' creates a temporary git worktree so the agent works "
+                        "on an isolated copy of the repo. Changes stay on a separate branch "
+                        "and can be reviewed/merged after completion."
+                    ),
+                },
+            },
+            "required": ["prompt"],
+        },
+    },
+    func=_agent_tool,
+    read_only=False,
+    concurrent_safe=False,
+))
+
+register_tool(ToolDef(
+    name="SendMessage",
+    schema={
+        "name": "SendMessage",
+        "description": (
+            "Send a follow-up message to a running background agent. "
+            "The message is queued and processed after the agent finishes its current work. "
+            "Reference agents by the name set via Agent(name=...) or by task ID."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "to":      {"type": "string", "description": "Agent name or task ID"},
+                "message": {"type": "string", "description": "Message to send to the agent"},
+            },
+            "required": ["to", "message"],
+        },
+    },
+    func=_send_message,
+    read_only=False,
+    concurrent_safe=True,
+))
+
+register_tool(ToolDef(
+    name="CheckAgentResult",
+    schema={
+        "name": "CheckAgentResult",
+        "description": "Check the status and result of a spawned sub-agent task.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "task_id": {"type": "string", "description": "Task ID returned by Agent tool"},
+            },
+            "required": ["task_id"],
+        },
+    },
+    func=_check_agent_result,
+    read_only=True,
+    concurrent_safe=True,
+))
+
+register_tool(ToolDef(
+    name="ListAgentTasks",
+    schema={
+        "name": "ListAgentTasks",
+        "description": "List all sub-agent tasks and their statuses.",
+        "input_schema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+    func=_list_agent_tasks,
+    read_only=True,
+    concurrent_safe=True,
+))
+
+register_tool(ToolDef(
+    name="AskMainAgentQuestion",
+    schema={
+        "name": "AskMainAgentQuestion",
+        "description": (
+            "Pause this sub-agent and ask the MAIN agent a question (not the user). "
+            "The sub-agent blocks in the current turn — full context is preserved — "
+            "and resumes once the main agent answers via SendMessage. "
+            "Use this when you need a decision, clarification, or permission from "
+            "the main agent before continuing. Examples: 'Should I also refactor X?', "
+            "'¿Deseas que haga algo más?', 'Plan looks like A or B — which one?'. "
+            "Only works when invoked from a sub-agent running in the background; "
+            "the main agent itself should use AskUserQuestion for the end user."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The question to ask the main agent.",
+                },
+            },
+            "required": ["question"],
+        },
+    },
+    func=_ask_main_agent_question,
+    read_only=False,
+    concurrent_safe=True,
+))
+
+register_tool(ToolDef(
+    name="ListAgentTypes",
+    schema={
+        "name": "ListAgentTypes",
+        "description": (
+            "List all available agent types (built-in and custom). "
+            "Use the type names as subagent_type when calling Agent."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+    func=_list_agent_types,
+    read_only=True,
+    concurrent_safe=True,
+))

offload_helper.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Offload Helper - Reemplazo para TmuxOffload
+Funciona con las herramientas tmux que sí funcionan
+"""
+
+import subprocess
+import time
+import uuid
+from typing import Optional, Dict, Any
+
+
+class TmuxJob:
+    """Representa un job ejecutado en tmux"""
+    
+    def __init__(self, command: str):
+        self.command = command
+        self.session = f"dulus_{uuid.uuid4().hex[:8]}"
+        self._created = False
+        self._start_time = None
+        
+    def start(self) -> str:
+        """Inicia el job en tmux detached. Retorna session ID."""
+        # Usar bash -c para soportar pipes y redirects
+        full_cmd = f"exec bash -c {repr(self.command)}"
+        
+        result = subprocess.run(
+            ["tmux", "new-session", "-d", "-s", self.session, full_cmd],
+            capture_output=True,
+            text=True
+        )
+        
+        if result.returncode != 0:
+            raise RuntimeError(f"tmux error: {result.stderr}")
+        
+        self._created = True
+        self._start_time = time.time()
+        return self.session
+    
+    def is_running(self) -> bool:
+        """Verifica si el job sigue corriendo"""
+        if not self._created:
+            return False
+        result = subprocess.run(
+            ["tmux", "has-session", "-t", self.session],
+            capture_output=True
+        )
+        return result.returncode == 0
+    
+    def capture(self, lines: int = 1000) -> str:
+        """Captura el output del job"""
+        if not self._created:
+            raise RuntimeError("Job no iniciado")
+        
+        result = subprocess.run(
+            ["tmux", "capture-pane", "-t", self.session, "-p", "-S", f"-{lines}"],
+            capture_output=True,
+            text=True
+        )
+        return result.stdout if result.returncode == 0 else ""
+    
+    def kill(self):
+        """Mata el job y la sesión tmux"""
+        if self._created:
+            subprocess.run(
+                ["tmux", "kill-session", "-t", self.session],
+                capture_output=True
+            )
+    
+    def wait(self, timeout: Optional[float] = None, poll_interval: float = 0.5) -> bool:
+        """
+        Espera a que termine el job.
+        Retorna True si terminó, False si timeout.
+        """
+        if not self._created:
+            raise RuntimeError("Job no iniciado")
+        
+        start = time.time()
+        while self.is_running():
+            if timeout and (time.time() - start) > timeout:
+                return False
+            time.sleep(poll_interval)
+        return True
+
+
+# === API SIMPLE ===
+
+def offload(command: str) -> str:
+    """
+    Ejecuta un comando en tmux detached (fire-and-forget).
+    Retorna el session ID para capturar después.
+    
+    Uso:
+        session = offload("sleep 10 && echo listo")
+        # ... más tarde ...
+        tmux capture-pane -t <session>:0.0 -p
+    """
+    job = TmuxJob(command)
+    return job.start()
+
+
+def offload_and_wait(command: str, timeout: Optional[float] = None) -> Dict[str, Any]:
+    """
+    Ejecuta comando y espera a que termine.
+    
+    Uso:
+        result = offload_and_wait("sleep 5 && date", timeout=10)
+        print(result['output'])  # stdout del comando
+    """
+    job = TmuxJob(command)
+    job.start()
+    finished = job.wait(timeout=timeout)
+    output = job.capture()
+    job.kill()
+    
+    return {
+        'session': job.session,
+        'output': output,
+        'finished': finished,
+        'timeout_reached': not finished
+    }
+
+
+def list_offloaded():
+    """Lista todas las sesiones dulus activas"""
+    result = subprocess.run(
+        ["tmux", "list-sessions"],
+        capture_output=True,
+        text=True
+    )
+    
+    if result.returncode != 0:
+        return []
+    
+    sessions = []
+    for line in result.stdout.strip().split('\n'):
+        if line.startswith('dulus_'):
+            sessions.append(line.split(':')[0])
+    return sessions
+
+
+# === EJEMPLOS ===
+
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) > 1 and sys.argv[1] == "demo":
+        print("🦅 Demo de Offload Helper")
+        print("=" * 40)
+        
+        # Demo 1: Fire and forget
+        print("\n1️⃣ Fire-and-forget:")
+        session = offload("echo 'Hola desde tmux!' && sleep 2 && date")
+        print(f"   Session: {session}")
+        print(f"   Para ver: tmux capture-pane -t {session}:0.0 -p")
+        
+        time.sleep(3)
+        output = subprocess.run(
+            ["tmux", "capture-pane", "-t", f"{session}:0.0", "-p"],
+            capture_output=True, text=True
+        ).stdout
+        print(f"   Output: {output.strip()[:50]}...")
+        
+        # Limpiar
+        subprocess.run(["tmux", "kill-session", "-t", session], capture_output=True)
+        
+        # Demo 2: Wait mode
+        print("\n2️⃣ Wait mode:")
+        result = offload_and_wait("echo 'Esperando...' && sleep 2 && echo 'Listo!' && date")
+        print(f"   Output: {result['output'].strip()}")
+        
+        # Demo 3: Listar
+        print("\n3️⃣ Sesiones activas:")
+        sessions = list_offloaded()
+        print(f"   {len(sessions)} sesiones dulus activas")
+        
+        print("\n✅ Todo funcionando!")
+    else:
+        print("Uso: python offload_helper.py demo")
+        print("\nFunciones:")
+        print("  offload(cmd) -> session_id")
+        print("  offload_and_wait(cmd, timeout) -> {output, session}")
+        print("  list_offloaded() -> [sessions]")

plugin/__init__.py

@@ -0,0 +1,22 @@
+"""Plugin system for dulus."""
+from .types import PluginManifest, PluginEntry, PluginScope, parse_plugin_identifier
+from .store import (
+    install_plugin, uninstall_plugin,
+    enable_plugin, disable_plugin, disable_all_plugins,
+    update_plugin, list_plugins, get_plugin,
+)
+from .loader import (
+    load_all_plugins, load_plugin_tools, load_plugin_skills,
+    load_plugin_mcp_configs, register_plugin_tools, reload_plugins,
+)
+from .recommend import recommend_plugins, recommend_from_files, format_recommendations
+
+__all__ = [
+    "PluginManifest", "PluginEntry", "PluginScope", "parse_plugin_identifier",
+    "install_plugin", "uninstall_plugin",
+    "enable_plugin", "disable_plugin", "disable_all_plugins",
+    "update_plugin", "list_plugins", "get_plugin",
+    "load_all_plugins", "load_plugin_tools", "load_plugin_skills",
+    "load_plugin_mcp_configs", "register_plugin_tools", "reload_plugins",
+    "recommend_plugins", "recommend_from_files", "format_recommendations",
+]