gdmcode 0.1.0__py3-none-any.whl

src/tools/agent_tools.py

@@ -0,0 +1,423 @@
+"""Agent sub-tools — plan, explore, verify, fork, resume, and run sub-agents.
+
+These tools expose the agent hierarchy to the model loop. Each tool creates a
+child AgentLoop with an appropriate model tier and a scoped task.
+
+Architecture mirrors Claude Code'"'"'s AgentTool system:
+  PlanAgentTool  — break a task into subtasks before executing (Thinker tier)
+  ExploreAgentTool — parallel research across codebase files (Scout tier)
+  VerifyAgentTool  — post-edit: re-read files + run tests + confirm (Coder tier)
+  ForkAgentTool   — spawn independent agent for a sub-task (background, Scout/Coder)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from src.models.definitions import ModelTier
+from src.models.schemas import TaskPlan
+from src.tools import REGISTRY, ToolBase, ToolResult
+
+if TYPE_CHECKING:
+    from src.agent.loop import AgentLoop
+    from src.config import GdmConfig
+
+__all__ = [
+    "PlanAgentTool",
+    "ExploreAgentTool",
+    "VerifyAgentTool",
+    "ForkAgentTool",
+    "SubAgentResult",
+    "SubAgentConfig",
+    "SubAgentRunner",
+]
+
+log = logging.getLogger(__name__)
+
+_MAX_PLAN_TURNS: int = 3
+
+# ---------------------------------------------------------------------------
+# SubAgentResult / SubAgentConfig / SubAgentRunner
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SubAgentResult:
+    """Result returned by a completed sub-agent run."""
+
+    success: bool
+    output: str
+    error: str | None = None
+    elapsed_s: float = 0.0
+    tool_calls: int = 0
+
+
+@dataclass
+class SubAgentConfig:
+    """Configuration for a single sub-agent invocation."""
+
+    task: str
+    model: str = "grok-3"
+    max_tokens: int = 4096
+    timeout_s: float = 120.0
+    tools: list[str] = field(default_factory=list)  # tool names to allow
+    context: str = ""  # extra context to inject
+
+
+class SubAgentRunner:
+    """Spawns child agents with isolated context to handle subtasks."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key
+
+    async def run(self, config: SubAgentConfig) -> SubAgentResult:
+        """Run a sub-agent for the given task. Returns result, never raises."""
+        start = time.monotonic()
+        try:
+            messages = self._build_messages(config)
+            loop = asyncio.get_running_loop()
+            output = await asyncio.wait_for(
+                loop.run_in_executor(None, self._call_model, messages, config),
+                timeout=config.timeout_s,
+            )
+            elapsed = time.monotonic() - start
+            return SubAgentResult(success=True, output=output, elapsed_s=elapsed)
+        except asyncio.TimeoutError:
+            elapsed = time.monotonic() - start
+            return SubAgentResult(
+                success=False, output="", error="timeout", elapsed_s=elapsed
+            )
+        except Exception as exc:  # noqa: BLE001
+            elapsed = time.monotonic() - start
+            return SubAgentResult(
+                success=False, output="", error=str(exc), elapsed_s=elapsed
+            )
+
+    async def run_parallel(
+        self, configs: list[SubAgentConfig]
+    ) -> list[SubAgentResult]:
+        """Run multiple sub-agents in parallel with asyncio.gather."""
+        return list(await asyncio.gather(*(self.run(c) for c in configs)))
+
+    def run_sync(self, config: SubAgentConfig) -> SubAgentResult:
+        """Sync wrapper for run(). Safe from both sync and async contexts."""
+        try:
+            return asyncio.run(self.run(config))
+        except RuntimeError:
+            # Already inside a running event loop — use a fresh thread
+            result_holder: list[SubAgentResult] = []
+            exc_holder: list[BaseException] = []
+
+            def _in_thread() -> None:
+                new_loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(new_loop)
+                try:
+                    result_holder.append(
+                        new_loop.run_until_complete(self.run(config))
+                    )
+                except BaseException as e:  # noqa: BLE001
+                    exc_holder.append(e)
+                finally:
+                    new_loop.close()
+
+            t = threading.Thread(target=_in_thread, daemon=True)
+            t.start()
+            t.join()
+            if exc_holder:
+                raise exc_holder[0]
+            return result_holder[0]
+
+    def _build_messages(self, config: SubAgentConfig) -> list[dict]:
+        """Build the messages list for the sub-agent call."""
+        system_lines = [
+            "You are a sub-agent. Complete the assigned task concisely."
+        ]
+        if config.tools:
+            system_lines.append(f"Available tools: {', '.join(config.tools)}")
+        messages: list[dict] = [
+            {"role": "system", "content": " ".join(system_lines)}
+        ]
+        user_content = (
+            f"{config.context}\n\n{config.task}"
+            if config.context
+            else config.task
+        )
+        messages.append({"role": "user", "content": user_content})
+        return messages
+
+    def _call_model(self, messages: list[dict], config: SubAgentConfig) -> str:
+        """Call the model API. Mocked in tests."""
+        try:
+            from src.models.router import ModelRouter  # noqa: F401
+        except ImportError:
+            pass
+
+        import openai
+
+        client = openai.OpenAI(
+            api_key=self._api_key or "dummy",
+            base_url="https://api.x.ai/v1",
+        )
+        resp = client.chat.completions.create(
+            model=config.model,
+            messages=messages,  # type: ignore[arg-type]
+            max_tokens=config.max_tokens,
+        )
+        if not resp.choices:
+            raise RuntimeError("No completion choices returned")
+        return resp.choices[0].message.content or ""
+
+_MAX_EXPLORE_TURNS: int = 5
+_MAX_VERIFY_TURNS: int = 4
+
+
+# ---------------------------------------------------------------------------
+# PlanAgentTool
+# ---------------------------------------------------------------------------
+
+class PlanAgentTool(ToolBase):
+    """Break a complex task into ordered subtasks before executing.
+
+    Spawns a Thinker-tier sub-agent whose only job is to produce a TaskPlan.
+    The plan is injected back into the parent agent'"'"'s context.
+    Should be called for any task touching 3+ files or requiring >1 edit pass.
+    """
+
+    name = "plan_agent"
+    description = (
+        "Break a complex task into ordered subtasks before executing. "
+        "Call this FIRST for any task touching 3+ files or with multiple edit passes. "
+        "Returns a structured plan with subtask list."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "task": {"type": "string", "description": "The task description to plan."},
+            "context": {
+                "type": "string",
+                "description": "Additional context: file paths, constraints, etc.",
+                "default": "",
+            },
+        },
+        "required": ["task"],
+    }
+
+    def __init__(self, cfg: Any, parent_loop: Any) -> None:  # cfg: GdmConfig, parent_loop: AgentLoop
+        self._cfg = cfg
+        self._parent = parent_loop
+
+    def execute(self, params: dict[str, Any]) -> ToolResult:
+        """Run a planning sub-agent. Returns the plan as formatted text."""
+        task = params.get("task", "")
+        context = params.get("context", "")
+        if not task:
+            return ToolResult(output="", error="plan_agent: 'task' param required")
+
+        plan_prompt = _build_plan_prompt(task, context)
+        result_text = self._run_sub_agent(plan_prompt, ModelTier.THINKER, _MAX_PLAN_TURNS)
+        return ToolResult(output=result_text)
+
+    def _run_sub_agent(self, prompt: str, tier: str, max_turns: int) -> str:
+        """Run a minimal sub-loop and collect the final RESPONSE."""
+        try:
+            return _collect_response(self._parent, prompt, tier)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("plan_agent sub-loop failed: %s", exc)
+            return f"Planning failed: {exc}"
+
+
+# ---------------------------------------------------------------------------
+# ExploreAgentTool
+# ---------------------------------------------------------------------------
+
+class ExploreAgentTool(ToolBase):
+    """Research codebase files in parallel to answer multiple questions.
+
+    Spawns up to 3 Scout-tier sub-agents (one per question) and merges results.
+    Use for: understanding existing code, finding patterns, locating implementations.
+    """
+
+    name = "explore_agent"
+    description = (
+        "Research multiple questions about the codebase in parallel. "
+        "Provide a list of questions; each is answered independently by a Scout agent. "
+        "Faster than sequential reads for 2+ unrelated questions."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "questions": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of research questions (max 3).",
+                "maxItems": 3,
+            },
+        },
+        "required": ["questions"],
+    }
+
+    def __init__(self, cfg: Any, parent_loop: Any) -> None:
+        self._cfg = cfg
+        self._parent = parent_loop
+
+    def execute(self, params: dict[str, Any]) -> ToolResult:
+        """Run Scout sub-agents for each question and merge results."""
+        questions: list[str] = params.get("questions", [])[:3]
+        if not questions:
+            return ToolResult(output="", error="explore_agent: at least 1 question required")
+
+        results: list[str] = []
+        for i, q in enumerate(questions, 1):
+            prompt = f"Research question {i}/{len(questions)}: {q}"
+            answer = _collect_response(self._parent, prompt, ModelTier.SCOUT)
+            results.append(f"Q{i}: {q}\nA: {answer}")
+
+        return ToolResult(output="\n\n---\n\n".join(results))
+
+
+# ---------------------------------------------------------------------------
+# VerifyAgentTool
+# ---------------------------------------------------------------------------
+
+class VerifyAgentTool(ToolBase):
+    """Post-edit verification: re-read modified files and run related tests.
+
+    Should be called after any multi-file edit session.
+    Spawns a Coder-tier sub-agent that re-reads all modified files and
+    checks that the changes are correct and tests pass.
+    """
+
+    name = "verify_agent"
+    description = (
+        "After editing files, verify changes are correct by re-reading and running tests. "
+        "Call after any multi-file edit. Returns pass/fail with details."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "files_modified": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths of files that were modified.",
+            },
+            "test_command": {
+                "type": "string",
+                "description": "Command to run tests (e.g., 'pytest tests/').",
+                "default": "pytest",
+            },
+        },
+        "required": ["files_modified"],
+    }
+
+    def __init__(self, cfg: Any, parent_loop: Any) -> None:
+        self._cfg = cfg
+        self._parent = parent_loop
+
+    def execute(self, params: dict[str, Any]) -> ToolResult:
+        """Verify modified files are correct and tests pass."""
+        files = params.get("files_modified", [])
+        test_cmd = params.get("test_command", "pytest")
+        if not files:
+            return ToolResult(output="", error="verify_agent: files_modified required")
+
+        prompt = _build_verify_prompt(files, test_cmd)
+        answer = _collect_response(self._parent, prompt, ModelTier.CODER)
+        return ToolResult(output=answer)
+
+
+# ---------------------------------------------------------------------------
+# ForkAgentTool
+# ---------------------------------------------------------------------------
+
+class ForkAgentTool(ToolBase):
+    """Spawn an independent background agent for a long-running sub-task.
+
+    The forked agent runs the task and writes results to the outbox.
+    The parent continues working; results are delivered via /tasks or btw queue.
+    Currently runs synchronously (Phase 2); true background execution in Phase 3.
+    """
+
+    name = "fork_agent"
+    description = (
+        "Fork an independent agent for a long-running sub-task. "
+        "The agent runs in the background while you continue. "
+        "Check /tasks for status. Use for: running full test suite, "
+        "refactoring a module, long analysis tasks."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "task": {"type": "string", "description": "The task for the forked agent."},
+            "model_tier": {
+                "type": "string",
+                "enum": ["scout", "coder", "thinker"],
+                "description": "Model tier to use. Default: coder.",
+                "default": "coder",
+            },
+        },
+        "required": ["task"],
+    }
+
+    def __init__(self, cfg: Any, parent_loop: Any) -> None:
+        self._cfg = cfg
+        self._parent = parent_loop
+
+    def execute(self, params: dict[str, Any]) -> ToolResult:
+        """Run the forked task (synchronously in Phase 2)."""
+        task = params.get("task", "")
+        tier = params.get("model_tier", ModelTier.CODER)
+        if not task:
+            return ToolResult(output="", error="fork_agent: 'task' param required")
+
+        log.info("Forking sub-agent (tier=%s): %s", tier, task[:80])
+        result = _collect_response(self._parent, task, tier)
+        return ToolResult(output=f"[Forked agent result]\n{result}")
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _collect_response(parent_loop: Any, prompt: str, tier: str) -> str:
+    """Run parent_loop for one prompt and collect RESPONSE events as text.
+
+    This is a simplified synchronous sub-agent invocation. Phase 3 will
+    make this truly asynchronous with isolated transcript + context.
+    """
+    from src.agent.loop import EventType
+
+    parts: list[str] = []
+    try:
+        for event in parent_loop.run(f"[sub-agent, tier={tier}] {prompt}"):
+            if event.type == EventType.RESPONSE:
+                parts.append(event.content)
+            elif event.type == EventType.DONE:
+                break
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Sub-agent loop error: %s", exc)
+        return f"Sub-agent error: {exc}"
+    return "".join(parts) or "(no response)"
+
+
+def _build_plan_prompt(task: str, context: str) -> str:
+    ctx_line = f"\nAdditional context: {context}" if context else ""
+    return (
+        f"Break this task into concrete, ordered subtasks:{ctx_line}\n\nTask: {task}\n\n"
+        "For each subtask specify: what to do, which file(s) to touch, "
+        "and what success looks like. Be specific and minimal."
+    )
+
+
+def _build_verify_prompt(files: list[str], test_cmd: str) -> str:
+    file_list = ", ".join(files)
+    return (
+        f"Verify these recently modified files are correct: {file_list}\n"
+        f"1. Re-read each file and confirm the changes look correct\n"
+        f"2. Run: {test_cmd}\n"
+        "3. Report: PASS if all tests pass and code looks correct, "
+        "FAIL with specific issues if not."
+    )

src/tools/ask_user_tool.py

@@ -0,0 +1,83 @@
+"""AskUserQuestionTool — interrupt the agent loop to ask a human question.
+
+This tool pauses the agent and presents a rich prompt to the user in the
+terminal. The agent must not proceed until the user answers.
+
+The tool returns the user's answer as a string. The agent should not call this
+tool for trivial choices — only when it is genuinely uncertain about something
+that could cause irreversible harm (e.g., "Are you sure you want to delete the
+production database?").
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar
+
+from rich.console import Console
+from rich.prompt import Prompt
+
+from src.tools import REGISTRY, ToolBase, ToolResult
+
+__all__ = ["AskUserQuestionTool"]
+
+log = logging.getLogger(__name__)
+_console = Console(stderr=True)
+
+
+class AskUserQuestionTool(ToolBase):
+    """Pause execution and ask the human user a question.
+
+    Use ONLY when:
+      1. The action is irreversible (delete, publish, send).
+      2. There is genuine ambiguity that cannot be resolved from context.
+      3. The user has not already answered via /allow-all or --yes.
+
+    Do NOT use for routine choices — make reasonable assumptions instead.
+    """
+
+    name: ClassVar[str] = "ask_user"
+    description: ClassVar[str] = (
+        "Ask the user a clarifying question and wait for their answer. "
+        "Only use for irreversible actions or genuine ambiguity. "
+        "Do not use for routine choices — make a reasonable assumption instead."
+    )
+    input_schema: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "required": ["question"],
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask the user.",
+            },
+            "default": {
+                "type": "string",
+                "description": "Default answer if the user presses Enter without typing.",
+            },
+        },
+        "additionalProperties": False,
+    }
+
+    def execute(self, params: dict[str, Any]) -> ToolResult:  # noqa: D102
+        question: str = params["question"]
+        default: str | None = params.get("default")
+
+        _console.print(f"\n[bold yellow]⚡ Agent question:[/bold yellow] {question}")
+        try:
+            answer = Prompt.ask(
+                "[bold]Your answer[/bold]",
+                default=default or "",
+                console=_console,
+            )
+        except (EOFError, KeyboardInterrupt):
+            answer = default or ""
+            _console.print("[dim]No answer received — using default.[/dim]")
+
+        log.info("AskUserQuestionTool: Q=%r A=%r", question, answer)
+        return ToolResult(output=answer, metadata={"question": question})
+
+
+# ---------------------------------------------------------------------------
+# Auto-register
+# ---------------------------------------------------------------------------
+
+REGISTRY.register(AskUserQuestionTool())