caudate-cli 0.1.0__py3-none-any.whl

core/worktree.py

@@ -0,0 +1,93 @@
+"""Worktree isolation — give a subagent its own checkout to mutate.
+
+A worktree is a separate working copy backed by the same `.git/` repo,
+created with `git worktree add`. The subagent gets full read/write
+access to its own copy without touching the parent's working tree. When
+the subagent finishes, the worktree is either kept (if it produced
+changes) or cleaned up (if it didn't), mirroring the SDK's contract.
+
+Two failure modes are handled gracefully:
+  - The repo is dirty in a way that blocks `worktree add` → return
+    `None`, caller should fall back to the shared tree.
+  - `git` isn't installed or the cwd isn't a git repo → same.
+
+Callers should treat worktree creation as best-effort: a failure is
+not an error, just a missed optimization.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+import tempfile
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Worktree:
+    path: Path
+    branch: str
+    parent_repo: Path
+
+    async def has_changes(self) -> bool:
+        """Did the subagent write anything?"""
+        rc, out, _ = await _git(self.path, "status", "--porcelain")
+        return rc == 0 and bool(out.strip())
+
+    async def cleanup(self, force: bool = False) -> None:
+        """Remove the worktree. Skips if it has uncommitted changes (unless force)."""
+        if not force and await self.has_changes():
+            logger.info(
+                f"Keeping worktree {self.path} — has uncommitted changes"
+            )
+            return
+        rc, _, err = await _git(
+            self.parent_repo, "worktree", "remove", "--force", str(self.path),
+        )
+        if rc != 0:
+            logger.debug(f"worktree remove failed: {err}")
+            shutil.rmtree(self.path, ignore_errors=True)
+        # Best-effort branch delete
+        await _git(self.parent_repo, "branch", "-D", self.branch)
+
+
+async def create_worktree(
+    parent_repo: Path | None = None,
+    base_branch: str = "HEAD",
+) -> Worktree | None:
+    """Create a fresh worktree off `base_branch`. Returns None on any failure."""
+    repo = parent_repo or Path.cwd()
+    if shutil.which("git") is None:
+        return None
+
+    rc, out, _ = await _git(repo, "rev-parse", "--show-toplevel")
+    if rc != 0:
+        return None
+    repo = Path(out.strip())
+
+    branch = f"cognos/agent-{uuid.uuid4().hex[:8]}"
+    tmp = Path(tempfile.mkdtemp(prefix="cognos-wt-"))
+    rc, _, err = await _git(
+        repo, "worktree", "add", "-b", branch, str(tmp), base_branch,
+    )
+    if rc != 0:
+        logger.debug(f"worktree add failed: {err}")
+        shutil.rmtree(tmp, ignore_errors=True)
+        return None
+    return Worktree(path=tmp, branch=branch, parent_repo=repo)
+
+
+async def _git(cwd: Path, *args: str) -> tuple[int, str, str]:
+    proc = await asyncio.create_subprocess_exec(
+        "git", *args,
+        cwd=str(cwd),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    out, err = await proc.communicate()
+    return proc.returncode or 0, out.decode(errors="ignore"), err.decode(errors="ignore")

execution/executor.py

@@ -0,0 +1,329 @@
+"""Executor — manages tool registry and executes tasks."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+from core.schemas import Task, ToolResult, ToolResultStatus, Episode
+from execution.tools.base import BaseTool
+from execution.tools.shell_tool import PowerShellTool, ShellTool
+from execution.tools.file_tool import FileReadTool, FileWriteTool
+from execution.tools.edit_tool import EditTool, FillInMiddleTool
+from execution.tools.glob_tool import GlobTool
+from execution.tools.grep_tool import GrepTool
+from execution.tools.notebook_tool import NotebookEditTool
+from execution.tools.ask_user_question_tool import AskUserQuestionTool
+from execution.tools.push_notification_tool import PushNotificationTool
+from execution.tools.cron_tool import CronCreateTool, CronDeleteTool, CronListTool
+from execution.tools.task_tool import (
+    TaskCreateTool, TaskGetTool, TaskListTool, TaskOutputTool, TaskStopTool,
+)
+from execution.tools.worktree_tool import EnterWorktreeTool, ExitWorktreeTool
+from execution.tools.mcp_tool import MCPListServersTool
+from execution.tools.plan_mode_tool import EnterPlanModeTool, ExitPlanModeTool
+from execution.tools.find_anywhere_tool import FindAnywhereTool
+from execution.tools.system_info_tool import SystemInfoTool
+from execution.tools.update_memory_tool import UpdateMemoryTool
+from execution.tools.artifact_tool import ArtifactTool
+from execution.tools.calculator_tool import CalculatorTool
+from execution.tools.datetime_tool import DateTimeTool
+from execution.tools.semantic_search_tool import SemanticSearchTool
+from execution.tools.describe_image_tool import DescribeImageTool
+from execution.tools.transcribe_audio_tool import TranscribeAudioTool
+from execution.tools.speak_tool import SpeakTool
+from execution.tools.http_request_tool import HttpRequestTool
+from execution.tools.sandbox_tool import SandboxTool
+from execution.tools.agentic_tool import AgenticTool, AgenticBrowseTool
+from execution.tools.openapi_tool import OpenAPITool
+from execution.tools.load_skill_tool import LoadSkillTool, RescanSkillsTool
+from execution.tools.cognos_card_tool import CognosCardTool
+from execution.tools.search_tool import WebSearchTool
+from execution.tools.web_fetch_tool import WebFetchTool
+from execution.tools.python_tool import PythonExecTool
+from execution.tools.respond_tool import RespondTool
+from execution.tools.think_tool import ThinkTool
+from execution.tools.agent_tool import AgentTool
+from execution.tools.draw_tool import DrawTool
+from execution.tools.edit_image_tool import EditImageTool
+from execution.tools.longcat_avatar_tool import LongCatAvatarTool
+from execution.tools.storyboard_tool import StoryboardTool
+
+
+# Legacy tool names mapped to their current canonical names. Kept for
+# backward-compat with plans/strategies stored from Phase 1.
+_LEGACY_ALIASES = {
+    "shell": "Bash",
+    "file_read": "Read",
+    "file_write": "Write",
+    "web_search": "WebSearch",
+    "python_exec": "PythonExec",
+    "respond": "Respond",
+    "think": "Think",
+}
+
+logger = logging.getLogger(__name__)
+
+
+class Executor:
+    """Tool registry and task execution engine."""
+
+    def __init__(self, llm=None, load_plugins: bool = True):
+        self._tools: dict[str, BaseTool] = {}
+        self._llm = llm
+        self._register_defaults()
+        if load_plugins:
+            self._load_plugins()
+
+    def _load_plugins(self) -> None:
+        """Auto-load community plugins from PLUGINS_DIR."""
+        try:
+            from config import PLUGINS_DIR
+            from execution.plugins import load_plugins as _load
+            count = _load(PLUGINS_DIR, self)
+            if count:
+                logger.info(f"Loaded {count} plugin tool(s) from {PLUGINS_DIR}")
+        except Exception as e:
+            logger.warning(f"Plugin loader failed: {e}")
+
+    def _register_defaults(self) -> None:
+        """Register built-in tools."""
+        think_tool = ThinkTool(llm=self._llm)
+        agent_tool = AgentTool()       # manager wired later by CognosAgent
+        # Read image-gen config from settings so users can swap model
+        # (e.g. FLUX.1-schnell vs SDXL-Turbo) without code changes.
+        # Falls back to DrawTool's own defaults if no `image` block.
+        try:
+            from core.settings import Settings
+            _img_cfg = Settings.load().get("image", {}) or {}
+        except Exception as e:
+            logger.warning(f"Failed to load image settings: {e}")
+            _img_cfg = {}
+        _img_backend = _img_cfg.get("backend", "diffusers")
+        _img_kwargs = {k: v for k, v in _img_cfg.items() if k != "backend"}
+        draw_tool = DrawTool(
+            backend=_img_backend, backend_kwargs=_img_kwargs,
+        )         # file_store wired later by CognosAgent
+        # Image-edit (img2img + Kontext). Reads `image_edit` settings
+        # block; falls back to defaults baked into DiffusersImageEdit.
+        try:
+            from core.settings import Settings
+            _edit_cfg = Settings.load().get("image_edit", {}) or {}
+        except Exception:
+            _edit_cfg = {}
+        _edit_backend = _edit_cfg.get("backend", "diffusers")
+        _edit_kwargs = {k: v for k, v in _edit_cfg.items() if k != "backend"}
+        edit_image_tool = EditImageTool(
+            backend=_edit_backend, backend_kwargs=_edit_kwargs,
+        )         # file_store wired later by CognosAgent
+        storyboard_tool = StoryboardTool(
+            llm=self._llm,
+        )         # file_store + image backends wired later by CognosAgent
+        # LongCat Avatar (WAN-S2V talking-head video) — drives a local
+        # ComfyUI server. URL overridable via COGNOS_COMFYUI_URL.
+        longcat_avatar_tool = LongCatAvatarTool(
+            comfyui_url=os.environ.get(
+                "COGNOS_COMFYUI_URL", "http://127.0.0.1:8188",
+            ),
+        )         # file_store wired later by CognosAgent
+        artifact_tool = ArtifactTool() # file_store wired later by CognosAgent
+        speak_tool = SpeakTool()       # file_store wired later by CognosAgent
+        for tool in [
+            ShellTool(),
+            PowerShellTool(),
+            FileReadTool(),
+            FileWriteTool(),
+            EditTool(),
+            FillInMiddleTool(),
+            GlobTool(),
+            GrepTool(),
+            NotebookEditTool(),
+            AskUserQuestionTool(),
+            PushNotificationTool(),
+            # Cron registry (read/create/delete)
+            CronListTool(),
+            CronCreateTool(),
+            CronDeleteTool(),
+            # Background task pool (TaskCreate needs the live agent —
+            # wired by CognosAgent.__init__ via set_agent())
+            TaskCreateTool(),
+            TaskListTool(),
+            TaskGetTool(),
+            TaskOutputTool(),
+            TaskStopTool(),
+            # MCP server visibility (needs the live agent)
+            MCPListServersTool(),
+            # Git worktrees
+            EnterWorktreeTool(),
+            ExitWorktreeTool(),
+            # Plan mode
+            EnterPlanModeTool(),
+            ExitPlanModeTool(),
+            FindAnywhereTool(),
+            SystemInfoTool(),
+            UpdateMemoryTool(),
+            CalculatorTool(),
+            DateTimeTool(),
+            SemanticSearchTool(),
+            DescribeImageTool(),
+            TranscribeAudioTool(),
+            HttpRequestTool(),
+            SandboxTool(),
+            AgenticTool(),
+            AgenticBrowseTool(),
+            OpenAPITool(),
+            LoadSkillTool(),
+            RescanSkillsTool(),
+            CognosCardTool(),
+            WebSearchTool(),
+            WebFetchTool(),
+            PythonExecTool(),
+            RespondTool(),
+            think_tool,
+            agent_tool,
+            draw_tool,
+            edit_image_tool,
+            longcat_avatar_tool,
+            storyboard_tool,
+            artifact_tool,
+            speak_tool,
+        ]:
+            self.register_tool(tool)
+
+        # Forge feature-CRUD tools — let the agent manage its own
+        # backlog when the orchestrator binds a project context.
+        # Outside of a forge run they refuse politely.
+        try:
+            from execution.tools.forge_feature_tools import FORGE_FEATURE_TOOLS
+            for cls in FORGE_FEATURE_TOOLS:
+                self.register_tool(cls())
+        except Exception as e:
+            logger.warning(f"Forge tool registration failed: {e}")
+
+    def set_llm(self, llm) -> None:
+        """Set or update the LLM for tools that need it."""
+        self._llm = llm
+        think = self.get_tool("think")
+        if think and hasattr(think, "set_llm"):
+            think.set_llm(llm)
+
+    def register_tool(self, tool: BaseTool) -> None:
+        """Register a tool."""
+        self._tools[tool.name] = tool
+        logger.debug(f"Registered tool: {tool.name}")
+
+    def get_tool(self, name: str) -> BaseTool | None:
+        if name in self._tools:
+            return self._tools[name]
+        # Fall back to legacy aliases
+        alias = _LEGACY_ALIASES.get(name)
+        if alias and alias in self._tools:
+            return self._tools[alias]
+        return None
+
+    def list_tools(self) -> list[str]:
+        return list(self._tools.keys())
+
+    def tool_definitions(self) -> list[dict]:
+        """Get LiteLLM-compatible tool definitions for tool calling."""
+        return [tool.to_tool_definition() for tool in self._tools.values()]
+
+    def tool_descriptions(self) -> str:
+        """Get descriptions for LLM context (legacy/display use)."""
+        lines = []
+        for name, tool in self._tools.items():
+            params = ", ".join(f"{k}: {v}" for k, v in tool.parameters.items())
+            lines.append(f"- {name}: {tool.description} ({params})")
+        return "\n".join(lines)
+
+    async def execute_tool(self, name: str, args: dict) -> ToolResult:
+        """Execute a tool by name with raw args (for agentic loop).
+
+        Unlike execute_task(), this takes raw name+args without a Task object.
+        """
+        tool = self.get_tool(name)
+        if tool is None:
+            return ToolResult(
+                tool_name=name,
+                status=ToolResultStatus.ERROR,
+                error=f"Unknown tool: {name}",
+            )
+        # Plan-mode gate: refuse any tool that mutates state. The two
+        # exceptions are EnterPlanMode/ExitPlanMode themselves so the
+        # agent can always toggle out.
+        try:
+            from core.plan_mode import is_active as _plan_active
+            if (
+                _plan_active()
+                and getattr(tool, "mutates", False)
+                and name not in ("EnterPlanMode", "ExitPlanMode")
+            ):
+                return ToolResult(
+                    tool_name=name,
+                    status=ToolResultStatus.ERROR,
+                    error=(
+                        f"Plan mode is ON — `{name}` mutates state "
+                        "and is blocked. Read-only tools still work. "
+                        "Call ExitPlanMode to allow mutations."
+                    ),
+                )
+        except Exception:
+            pass  # plan_mode module missing → behave as if mode is off
+        try:
+            return await tool.execute(**args)
+        except Exception as e:
+            return ToolResult(
+                tool_name=name,
+                status=ToolResultStatus.ERROR,
+                error=str(e),
+            )
+
+    async def execute_task(self, task: Task) -> tuple[ToolResult, Episode]:
+        """Execute a single task and return result + episode record."""
+        task.attempts += 1
+        start = time.time()
+
+        # Normalize "null"/"none" strings to actual None
+        if task.tool_name and task.tool_name.lower() in ("null", "none", "reasoning"):
+            task.tool_name = None
+
+        if not task.tool_name:
+            # Pure reasoning task — no tool to execute
+            result = ToolResult(
+                tool_name="reasoning",
+                status=ToolResultStatus.SUCCESS,
+                output=task.description,
+            )
+        else:
+            tool = self.get_tool(task.tool_name)
+            if tool is None:
+                result = ToolResult(
+                    tool_name=task.tool_name,
+                    status=ToolResultStatus.ERROR,
+                    error=f"Unknown tool: {task.tool_name}",
+                )
+            else:
+                try:
+                    result = await tool.execute(**task.tool_args)
+                except Exception as e:
+                    result = ToolResult(
+                        tool_name=task.tool_name,
+                        status=ToolResultStatus.ERROR,
+                        error=str(e),
+                    )
+
+        result.duration_ms = (time.time() - start) * 1000
+
+        episode = Episode(
+            goal_id=task.goal_id,
+            task_id=task.id,
+            action=task.description,
+            tool_name=task.tool_name,
+            tool_args=task.tool_args,
+            result=result,
+        )
+
+        logger.info(f"Executed task '{task.description}': {result.status.value} ({result.duration_ms:.0f}ms)")
+        return result, episode

execution/plugins.py

@@ -0,0 +1,108 @@
+"""Plugin loader — discover and register community tools from a directory.
+
+Each plugin is a Python file in the plugins directory that exposes ONE of:
+
+  1. A module-level variable `PLUGIN` assigned to a BaseTool subclass instance:
+        from execution.tools.base import BaseTool
+        class Hello(BaseTool):
+            ...
+        PLUGIN = Hello()
+
+  2. A module-level `register(executor)` callable that registers tools itself:
+        def register(executor):
+            executor.register_tool(MyToolA())
+            executor.register_tool(MyToolB())
+
+Plugins are discovered from `plugins/*.py` (skipping files whose names start
+with `_`) and `plugins/*/plugin.py` for package-style plugins.
+
+Failures in one plugin never prevent loading the others — they're logged
+and skipped.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def load_plugins(plugin_dir: Path, executor: Any) -> int:
+    """Discover and register every plugin in `plugin_dir`. Returns count registered."""
+    if not plugin_dir.exists():
+        return 0
+
+    count = 0
+    for path in _discover(plugin_dir):
+        try:
+            registered = _load_one(path, executor)
+        except Exception as e:
+            logger.warning(f"Plugin {path} failed to load: {e}")
+            continue
+        count += registered
+    return count
+
+
+def _discover(plugin_dir: Path) -> list[Path]:
+    """Return every plugin entry point under `plugin_dir`.
+
+    - Top-level files: plugin_dir/*.py (skipping _-prefixed and __init__)
+    - Package style: plugin_dir/<name>/plugin.py
+    """
+    entries: list[Path] = []
+    for path in sorted(plugin_dir.glob("*.py")):
+        name = path.stem
+        if name.startswith("_"):
+            continue
+        entries.append(path)
+    for path in sorted(plugin_dir.glob("*/plugin.py")):
+        entries.append(path)
+    return entries
+
+
+def _load_one(path: Path, executor: Any) -> int:
+    """Import `path` as a module and register whatever it exposes."""
+    module_name = f"cognos_plugin_{path.parent.name}_{path.stem}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+    registered = 0
+
+    # Preferred: explicit register() callable
+    register_fn = getattr(module, "register", None)
+    if callable(register_fn):
+        before = len(executor.list_tools())
+        register_fn(executor)
+        registered = len(executor.list_tools()) - before
+        logger.info(f"Plugin {path.name}: register() added {registered} tool(s)")
+        return registered
+
+    # Alternative: a PLUGIN variable pointing to a BaseTool instance (or list)
+    plugin_obj = getattr(module, "PLUGIN", None)
+    if plugin_obj is None:
+        logger.warning(
+            f"Plugin {path.name} has neither PLUGIN nor register() — skipping"
+        )
+        return 0
+
+    candidates = plugin_obj if isinstance(plugin_obj, (list, tuple)) else [plugin_obj]
+    for obj in candidates:
+        if not isinstance(obj, BaseTool):
+            logger.warning(
+                f"Plugin {path.name} PLUGIN entry {obj!r} is not a BaseTool instance"
+            )
+            continue
+        executor.register_tool(obj)
+        registered += 1
+    logger.info(f"Plugin {path.name}: registered {registered} tool(s)")
+    return registered

execution/tools/agent_tool.py

@@ -0,0 +1,107 @@
+"""Agent tool — the Respond-like primitive that lets the parent spawn subagents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class AgentTool(BaseTool):
+    name = "Agent"
+    description = (
+        "Spawn a subagent OR dispatch a message on the inter-agent bus.\n\n"
+        "Spawn mode (default): supply `task` (+ optional `subagent_type`, "
+        "`isolation`) to spawn a child agent and wait for its summary. "
+        "Available subagent_types: general-purpose, research, code-review, "
+        "executor_brain, critic_brain.\n\n"
+        "Bus mode: supply `recipient_agent_id` "
+        "(executor_brain_01 or critic_brain_02) plus `payload_context`. "
+        "Set `suspend_sender_state=true` to wait for the recipient's "
+        "reply; otherwise fire-and-forget."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "Spawn mode: what the subagent should accomplish. Be specific — the subagent does not see your context.",
+                },
+                "subagent_type": {
+                    "type": "string",
+                    "description": "Spawn mode preset",
+                    "enum": ["general-purpose", "research", "code-review",
+                            "executor_brain", "critic_brain"],
+                    "default": "general-purpose",
+                },
+                "isolation": {
+                    "type": "string",
+                    "description": "Spawn mode: set 'worktree' for an isolated working copy. Best-effort.",
+                    "enum": ["worktree"],
+                },
+                "recipient_agent_id": {
+                    "type": "string",
+                    "description": "Bus mode: which agent to message.",
+                    "enum": ["executor_brain_01", "critic_brain_02"],
+                },
+                "payload_context": {
+                    "type": "string",
+                    "description": "Bus mode: message body delivered to the recipient.",
+                },
+                "suspend_sender_state": {
+                    "type": "boolean",
+                    "description": "Bus mode: if true, await the recipient's reply before returning.",
+                    "default": False,
+                },
+            },
+        }
+
+    def __init__(self, manager=None):
+        self._manager = manager
+
+    def set_manager(self, manager) -> None:
+        self._manager = manager
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        if self._manager is None:
+            return self._error("SubagentManager not configured")
+
+        recipient = kwargs.get("recipient_agent_id")
+        if recipient:
+            payload = kwargs.get("payload_context", "")
+            if not payload:
+                return self._error("payload_context required in bus mode")
+            suspend = bool(kwargs.get("suspend_sender_state", False))
+            try:
+                reply = await self._manager.dispatch(
+                    sender_id="agent_tool",
+                    recipient_id=recipient,
+                    context=payload,
+                    suspend_sender=suspend,
+                )
+            except Exception as e:
+                return self._error(f"Bus dispatch failed: {e}")
+            if suspend:
+                return self._success(str(reply) if reply is not None else "(no reply)")
+            return self._success(f"Message queued for {recipient}.")
+
+        task = kwargs.get("task", "")
+        subagent_type = kwargs.get("subagent_type", "general-purpose")
+        isolation = kwargs.get("isolation")
+
+        if not task:
+            return self._error("No task provided (and no recipient_agent_id for bus mode)")
+
+        run = await self._manager.run_one(
+            task, subagent_type=subagent_type, isolation=isolation,
+        )
+        if run.error:
+            return self._error(f"Subagent {run.id} failed: {run.error}")
+        result = run.result or "(no output)"
+        if run.worktree_path:
+            result += f"\n\n[worktree: {run.worktree_path} branch={run.worktree_branch}]"
+        return self._success(result)