caudate-cli 0.1.0__py3-none-any.whl

execution/tools/update_memory_tool.py

@@ -0,0 +1,92 @@
+"""UpdateMemory — write to the durable cross-session memory.md.
+
+Three modes:
+  - `append`  : add a new entry to the bottom of memory.md
+  - `replace` : wholesale rewrite (use sparingly — destructive)
+  - `read`    : return current contents (the LLM doesn't normally need
+                this since memory.md is auto-injected into the system
+                prompt every turn, but it's useful when the user asks
+                "what do you remember?")
+
+Caudate's `memory_write` head also writes to this file automatically
+when she predicts a turn is memory-worthy (above threshold) — that
+path goes through `nn/observer.py` and bypasses this tool. The tool
+exists for *explicit* memory updates the LLM (or user) wants to make.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.memory_md import get_memory
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class UpdateMemoryTool(BaseTool):
+    mutates = True
+    name = "UpdateMemory"
+    description = (
+        "Manage Cognos's durable cross-session memory file. "
+        "Use this when the user says 'remember X', 'note that...', or "
+        "you want to record an important fact for future sessions. "
+        "Modes: 'append' (add a new entry), 'replace' (rewrite the whole "
+        "file — destructive, only use when explicitly asked to clean up), "
+        "'read' (return current contents). Memory is automatically "
+        "injected into your system prompt every turn — you don't need to "
+        "call 'read' to access it under normal flow."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "mode": {
+                    "type": "string",
+                    "enum": ["append", "replace", "read"],
+                    "description": "What to do with memory.md.",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "For 'append' or 'replace': the text to write.",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Optional short title for an 'append' entry.",
+                },
+            },
+            "required": ["mode"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        mode = (kwargs.get("mode") or "").lower()
+        memory = get_memory()
+        if mode == "read":
+            text = memory.read()
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=text or "(memory.md is empty)",
+            )
+        content = (kwargs.get("content") or "").strip()
+        if not content:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="content is required for append/replace mode",
+            )
+        if mode == "append":
+            memory.append(content, source="explicit", title=kwargs.get("title", ""))
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=f"Appended to memory.md ({len(content)} chars)",
+            )
+        if mode == "replace":
+            memory.replace(content)
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=f"Replaced memory.md ({len(content)} chars)",
+            )
+        return ToolResult(
+            tool_name=self.name, status="error",
+            error=f"unknown mode {mode!r}; expected append/replace/read",
+        )

execution/tools/web_fetch_tool.py

@@ -0,0 +1,82 @@
+"""WebFetch tool — fetch a URL and return cleaned text."""
+
+from __future__ import annotations
+
+import asyncio
+import html
+import re
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class WebFetchTool(BaseTool):
+    name = "WebFetch"
+    description = (
+        "Fetch a web page and return its text content with HTML stripped. "
+        "Use for reading documentation, articles, or any web resource."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "The URL to fetch (must start with http:// or https://)",
+                },
+                "max_chars": {
+                    "type": "integer",
+                    "description": "Max characters to return (default 20000)",
+                    "default": 20000,
+                },
+            },
+            "required": ["url"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        url = kwargs.get("url", "")
+        if not url:
+            return self._error("No url provided")
+        if not url.startswith(("http://", "https://")):
+            return self._error(f"Invalid URL scheme: {url}")
+
+        max_chars = int(kwargs.get("max_chars", 20000))
+
+        cmd = f'curl -sSL --max-time 30 -A "cognos-agent/1.0" "{url}"'
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=35)
+        except asyncio.TimeoutError:
+            return self._error("Fetch timed out")
+        except Exception as e:
+            return self._error(str(e))
+
+        if proc.returncode != 0:
+            return self._error(f"curl failed: {stderr.decode(errors='ignore')[:200]}")
+
+        raw = stdout.decode(errors="ignore")
+        text = _strip_html(raw)
+        if len(text) > max_chars:
+            text = text[:max_chars] + f"\n\n... (truncated at {max_chars} chars)"
+        return self._success(text)
+
+
+_SCRIPT_STYLE_RE = re.compile(r"<(script|style)[^>]*>.*?</\1>", re.DOTALL | re.IGNORECASE)
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\n\s*\n+")
+
+
+def _strip_html(raw: str) -> str:
+    """Very basic HTML → text conversion (no external deps)."""
+    raw = _SCRIPT_STYLE_RE.sub("", raw)
+    raw = _TAG_RE.sub("", raw)
+    raw = html.unescape(raw)
+    raw = _WS_RE.sub("\n\n", raw)
+    return raw.strip()

execution/tools/worktree_tool.py

@@ -0,0 +1,174 @@
+"""Worktree tools — git worktree isolation for agent work.
+
+`git worktree` creates a separate working copy backed by the same
+`.git/` repo. Useful when you want the agent to try a risky change
+without touching the live working tree, or to work on multiple
+branches in parallel.
+
+Two tools (matching Claude Code's surface):
+
+  - **`EnterWorktree`** — create a fresh worktree off HEAD (or a given
+    base branch) and remember it as the "active" worktree. Returns
+    its path + branch name. Subsequent file operations should be
+    targeted at that path explicitly (these tools are advisory; they
+    don't reroute Edit/Write to the worktree automatically).
+  - **`ExitWorktree`** — clean up the active worktree. By default
+    keeps it if there are uncommitted changes (so work isn't lost);
+    pass `force=true` to delete regardless.
+
+Process-local: the active worktree handle lives in this module. Not
+persisted; restart wipes it.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from core.worktree import Worktree, create_worktree
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+# Process-wide active worktree. Multiple tools share this so the
+# `ExitWorktree` call doesn't need an id.
+_ACTIVE: Worktree | None = None
+
+
+class EnterWorktreeTool(BaseTool):
+    mutates = True
+    name = "EnterWorktree"
+    description = (
+        "Create a temporary git worktree (separate working copy backed "
+        "by the same `.git/` repo) so changes can be tried in "
+        "isolation. Optional `base_branch` (default HEAD). Returns the "
+        "worktree path and a fresh branch name. Use `ExitWorktree` "
+        "afterwards to clean up. Note: file-modifying tools (Edit, "
+        "Write, Bash) don't auto-route to the worktree — pass the "
+        "returned path explicitly when running them."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "base_branch": {
+                    "type": "string",
+                    "description": "Branch or commit to base the worktree on. Default 'HEAD'.",
+                    "default": "HEAD",
+                },
+                "parent_repo": {
+                    "type": "string",
+                    "description": "Path to the parent repo. Default = current working dir.",
+                },
+            },
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        global _ACTIVE
+        if _ACTIVE is not None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(
+                    f"a worktree is already active at {_ACTIVE.path}. "
+                    "Call ExitWorktree first."
+                ),
+            )
+        base = (kwargs.get("base_branch") or "HEAD").strip()
+        parent_str = (kwargs.get("parent_repo") or "").strip()
+        parent = Path(parent_str).expanduser().resolve() if parent_str else None
+        wt = await create_worktree(parent_repo=parent, base_branch=base)
+        if wt is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(
+                    "git worktree creation failed. Check that the cwd "
+                    "is a git repo, git is installed, and the working "
+                    "tree isn't blocked by uncommitted submodule state."
+                ),
+            )
+        _ACTIVE = wt
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Worktree created.\n"
+                f"  path:    {wt.path}\n"
+                f"  branch:  {wt.branch}\n"
+                f"  parent:  {wt.parent_repo}\n"
+                "Use this path explicitly when running file-modifying "
+                "tools. Call ExitWorktree to clean up."
+            ),
+            metadata={
+                "path":   str(wt.path),
+                "branch": wt.branch,
+                "parent": str(wt.parent_repo),
+            },
+        )
+
+
+class ExitWorktreeTool(BaseTool):
+    mutates = True
+    name = "ExitWorktree"
+    description = (
+        "Clean up the active worktree created by EnterWorktree. By "
+        "default it's KEPT if there are uncommitted changes (work "
+        "isn't silently lost). Pass `force: true` to delete anyway. "
+        "Returns whether it was removed or kept, plus the path so you "
+        "can inspect it manually."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "force": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, delete even if there are uncommitted "
+                        "changes (DESTRUCTIVE). Default false."
+                    ),
+                    "default": False,
+                },
+            },
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        global _ACTIVE
+        if _ACTIVE is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="no active worktree (call EnterWorktree first)",
+            )
+        force = bool(kwargs.get("force", False))
+        path = _ACTIVE.path
+        had_changes = await _ACTIVE.has_changes()
+        kept = had_changes and not force
+        try:
+            await _ACTIVE.cleanup(force=force)
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"cleanup failed: {e}",
+            )
+        _ACTIVE = None
+        if kept:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=(
+                    f"Worktree kept (uncommitted changes present).\n"
+                    f"  path: {path}\n"
+                    "Pass force=true to delete anyway, or commit/push "
+                    "the changes before exiting."
+                ),
+                metadata={"path": str(path), "kept": True},
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=f"Worktree removed: {path}",
+            metadata={"path": str(path), "kept": False},
+        )

llm/fallback.py

@@ -0,0 +1,116 @@
+"""FallbackLLMProvider — try a chain of providers in order on failure.
+
+Wraps a primary provider plus an ordered list of fallbacks. On a
+*retryable* failure (network blip, timeout, model overloaded, 5xx) it
+moves to the next provider. On a deterministic failure (bad request,
+model not found) it raises immediately — falling back wouldn't help.
+
+Maintains the same surface as `LLMProvider` so anywhere that takes one
+will also take this. The router (`DualLLMProvider`) is orthogonal and
+can sit on top of fallbacks (each tier becomes a fallback chain).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator
+
+from pydantic import BaseModel
+
+from core.schemas import StreamEvent
+from llm.provider import LLMProvider, LLMResponse, _is_retryable
+
+logger = logging.getLogger(__name__)
+
+
+class FallbackLLMProvider:
+    """LLMProvider with an ordered fallback chain.
+
+    The first provider's `model` is exposed via `.model` so existing
+    code that treats this as an LLMProvider still gets a sensible value
+    for logging / status lines.
+    """
+
+    def __init__(self, primary: LLMProvider, fallbacks: list[LLMProvider]):
+        if not isinstance(primary, LLMProvider):
+            raise TypeError("primary must be an LLMProvider")
+        self._chain: list[LLMProvider] = [primary, *fallbacks]
+        self._active_idx = 0
+
+    @property
+    def model(self) -> str:
+        return self._chain[self._active_idx].model
+
+    @property
+    def temperature(self) -> float:
+        return self._chain[self._active_idx].temperature
+
+    @property
+    def max_tokens(self) -> int:
+        return self._chain[self._active_idx].max_tokens
+
+    def switch_model(self, model: str) -> None:
+        """Switch the *primary* provider's model. Fallbacks are unchanged."""
+        self._chain[0].switch_model(model)
+
+    # ------------------------------------------------------------------
+
+    async def chat(self, *args: Any, **kwargs: Any) -> LLMResponse:
+        return await self._call("chat", *args, **kwargs)
+
+    async def complete(self, *args: Any, **kwargs: Any) -> LLMResponse:
+        return await self._call("complete", *args, **kwargs)
+
+    async def structured_output(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._call("structured_output", *args, **kwargs)
+
+    async def stream(
+        self, *args: Any, **kwargs: Any,
+    ) -> AsyncIterator[StreamEvent]:
+        last_err: BaseException | None = None
+        for i, provider in enumerate(self._chain):
+            try:
+                async for evt in provider.stream(*args, **kwargs):
+                    yield evt
+                self._active_idx = i
+                return
+            except Exception as e:
+                last_err = e
+                if not _is_retryable(e) or i == len(self._chain) - 1:
+                    raise
+                logger.warning(
+                    f"Stream via {provider.model!r} failed ({e}); "
+                    f"falling back to {self._chain[i + 1].model!r}"
+                )
+        if last_err:
+            raise last_err
+
+    async def _call(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        last_err: BaseException | None = None
+        for i, provider in enumerate(self._chain):
+            try:
+                fn = getattr(provider, method)
+                result = await fn(*args, **kwargs)
+                self._active_idx = i
+                return result
+            except Exception as e:
+                last_err = e
+                if not _is_retryable(e) or i == len(self._chain) - 1:
+                    raise
+                logger.warning(
+                    f"{method} via {provider.model!r} failed ({e}); "
+                    f"falling back to {self._chain[i + 1].model!r}"
+                )
+        if last_err:
+            raise last_err
+
+
+def build_fallback(
+    primary: LLMProvider,
+    fallback_models: list[str],
+) -> LLMProvider | FallbackLLMProvider:
+    """Construct a FallbackLLMProvider, or return primary if no fallbacks."""
+    if not fallback_models:
+        return primary
+    fallbacks = [LLMProvider(model=m) for m in fallback_models]
+    return FallbackLLMProvider(primary=primary, fallbacks=fallbacks)