gdmcode 0.1.0__py3-none-any.whl

src/agent/tool_orchestrator.py

@@ -0,0 +1,402 @@
+"""Tool orchestrator — permission-checked, audited tool dispatch.
+
+Every tool call the agent wants to make flows through ToolOrchestrator.execute().
+This is the single choke point for:
+  1. Permission gating (PermissionContext)
+  2. Tool result cache (read-only tools, mtime-keyed LRU)
+  3. Tool execution (REGISTRY)
+  4. Audit logging (AuditLogger)
+  5. Post-write hooks (FileCache invalidation + CodeIndex re-index)
+
+Tools are guaranteed to be registered before the first execute() call because
+_ensure_tools_registered() runs at module import time.
+"""
+from __future__ import annotations
+
+import concurrent.futures as _cf
+import copy
+import json
+import logging
+import os
+import threading
+from collections import OrderedDict
+from typing import Any
+
+from src._internal.constants import _ALWAYS_DENY_TOOLS, _WRITE_TOOLS
+from src.exceptions import ToolPermissionError
+from src.security import AuditLogger
+from src.tools import REGISTRY, ToolResult
+
+__all__ = ["ToolOrchestrator"]
+
+log = logging.getLogger(__name__)
+
+_TOOL_TIMEOUT_S: int = 30
+# Module-level executor: tools run in a separate thread so a hung tool cannot
+# freeze the agent loop.  daemon=True so threads don't block process exit.
+_TOOL_EXECUTOR: _cf.ThreadPoolExecutor = _cf.ThreadPoolExecutor(
+    max_workers=4, thread_name_prefix="gdm-tool"
+)
+
+# Shell tool names where we cap the tool's own subprocess timeout to orchestrator timeout.
+_SHELL_TOOLS: frozenset[str] = frozenset({"bash", "powershell"})
+
+
+def shutdown_tool_executor() -> None:
+    """Signal the tool executor to stop accepting jobs and cancel pending futures.
+
+    Called from the flush path (SIGTERM, atexit) to avoid lingering tool threads
+    after the agent loop has finished.
+    """
+    _TOOL_EXECUTOR.shutdown(wait=False, cancel_futures=True)
+
+
+# ---------------------------------------------------------------------------
+# Tool result cache
+# ---------------------------------------------------------------------------
+
+# Only path-scoped read tools may be cached.  Expand this set as new read tools
+# are added — never add non-existent tools (spec: audit finding).
+_CACHEABLE_TOOLS: frozenset[str] = frozenset({"read_file"})
+# Both write tools must invalidate cached reads of the same path.
+_INVALIDATING_TOOLS: frozenset[str] = _WRITE_TOOLS   # {"write_file", "edit_file"}
+_MAX_CACHE_ENTRIES: int = 100
+
+
+class _ToolResultCache:
+    """Thread-safe mtime-keyed LRU cache for pure read tool results.
+
+    Key = tool_name : abs_path : mtime : sorted_extra_args_json.
+    Returns deepcopy of stored result to prevent caller mutation of cache.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._store: OrderedDict[str, ToolResult] = OrderedDict()
+        self._hits: int = 0
+        self._misses: int = 0
+
+    # ------------------------------------------------------------------
+    def _cache_key(self, tool_name: str, args: dict[str, Any]) -> str | None:
+        if tool_name not in _CACHEABLE_TOOLS:
+            return None
+        path_str = args.get("path")
+        if not path_str:
+            return None
+        try:
+            mtime = os.path.getmtime(path_str)
+        except OSError:
+            return None
+        extra = {k: v for k, v in args.items() if k != "path"}
+        arg_sig = json.dumps(extra, sort_keys=True)
+        return f"{tool_name}:{path_str}:{mtime:.6f}:{arg_sig}"
+
+    # ------------------------------------------------------------------
+    def get(self, tool_name: str, args: dict[str, Any]) -> ToolResult | None:
+        key = self._cache_key(tool_name, args)
+        if key is None:
+            return None
+        with self._lock:
+            if key in self._store:
+                self._store.move_to_end(key)
+                self._hits += 1
+                log.debug("cache HIT  %s(%s)", tool_name, args.get("path", ""))
+                return copy.deepcopy(self._store[key])
+            self._misses += 1
+            return None
+
+    def put(self, tool_name: str, args: dict[str, Any], result: ToolResult) -> None:
+        key = self._cache_key(tool_name, args)
+        if key is None:
+            return
+        with self._lock:
+            self._store[key] = copy.deepcopy(result)
+            self._store.move_to_end(key)
+            while len(self._store) > _MAX_CACHE_ENTRIES:
+                self._store.popitem(last=False)
+
+    def invalidate_path(self, path_str: str) -> int:
+        """Remove all entries whose key references *path_str*. Returns count removed."""
+        with self._lock:
+            to_delete = [k for k in self._store if f":{path_str}:" in k]
+            for k in to_delete:
+                del self._store[k]
+            return len(to_delete)
+
+    def stats(self) -> dict[str, object]:
+        with self._lock:
+            total = self._hits + self._misses
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": self._hits / total if total else 0.0,
+                "size": len(self._store),
+            }
+
+
+# Module-level cache instance shared across all ToolOrchestrator instances in the process.
+_TOOL_CACHE: _ToolResultCache = _ToolResultCache()
+
+
+# ---------------------------------------------------------------------------
+# Bootstrap — import all tool modules so they self-register with REGISTRY
+# ---------------------------------------------------------------------------
+
+def _ensure_tools_registered() -> None:
+    """Import all tool modules so they register themselves with REGISTRY."""
+    import src.tools.bash_tool      # noqa: F401
+    import src.tools.read_tools     # noqa: F401
+    import src.tools.search_tools   # noqa: F401
+    import src.tools.shell_tools    # noqa: F401
+    import src.tools.ask_user_tool  # noqa: F401
+    import src.tools.write_tools    # noqa: F401
+    import src.tools.dep_tools      # noqa: F401
+    import src.tools.impact_tools   # noqa: F401
+    import src.tools.browser_tool   # noqa: F401
+
+
+_ensure_tools_registered()
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+class ToolOrchestrator:
+    """Permission-checked, audited dispatcher for all agent tool calls.
+
+    Every tool invocation goes through this class in order:
+    1. PermissionContext.check() -- may raise ToolPermissionError
+    2. REGISTRY.call() -- executes the tool
+    3. AuditLogger.log_tool() -- writes an immutable audit record
+    4. Post-write hooks (FileCache invalidation + CodeIndex re-index)
+
+    The execute() method never raises. All errors are surfaced as
+    ToolResult(error=...).
+
+    Usage::
+
+        orch = ToolOrchestrator(permissions=ctx, db=db, session_id=sid)
+        result = orch.execute("bash", {"command": "ls"})
+        if not result.ok:
+            console.print(result.error)
+    """
+
+
+    def __init__(
+        self,
+        permissions: Any,  # PermissionContext -- typed as Any to avoid circular import
+        db: Any,           # GdmDatabase -- typed as Any to avoid circular import
+        session_id: str,
+        *,
+        project_id: str = "",
+        cfg: Any = None,   # GdmConfig | None -- for timeout config
+    ) -> None:
+        self._permissions = permissions
+        self._audit = AuditLogger(db=db, session_id=session_id)
+        self._session_id = session_id
+        self._db = db
+        self._project_id = project_id
+        self._timeout_secs: int = (
+            cfg.tools_timeout_secs if cfg is not None else _TOOL_TIMEOUT_S
+        )
+        # plugin_name.tool_name → (IpcPluginHandle, raw_tool_name)
+        self._plugin_channels: dict[str, Any] = {}
+
+    def execute(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        *,
+        model_id: str = "unknown",
+    ) -> ToolResult:
+        """Check permissions, run tool, write audit record. Never raises.
+
+        Args:
+            tool_name: name of the tool to invoke (must match REGISTRY entry)
+            args: parsed arguments dict for the tool
+            model_id: model that requested this call, for the audit log
+
+        Returns:
+            ToolResult -- inspect .ok to distinguish success from failure.
+        """
+        try:
+            decision = self._permissions.check(tool_name, args)
+        except ToolPermissionError as exc:
+            self._audit.log_denied(
+                tool=tool_name, args=args, reason=str(exc), model=model_id
+            )
+            return ToolResult(
+                output="",
+                error=f"Tool {tool_name!r} denied: {exc}",
+            )
+
+        _fut: _cf.Future[ToolResult] | None = None
+        try:
+            # Check cache before executing (read-only tools only)
+            cached = _TOOL_CACHE.get(tool_name, args)
+            if cached is not None:
+                log.debug("cache stats: %s", _TOOL_CACHE.stats())
+                self._audit.log_tool(
+                    tool=tool_name, args=args, model=model_id, decision="cache_hit"
+                )
+                return cached
+
+            # For shell tools, cap subprocess timeout at orchestrator timeout so the
+            # subprocess is killed (not abandoned) when the orchestrator times out.
+            if tool_name in _SHELL_TOOLS:
+                effective_args = dict(args)
+                user_timeout = int(effective_args.get("timeout", self._timeout_secs))
+                effective_args["timeout"] = min(user_timeout, self._timeout_secs)
+            else:
+                effective_args = args
+
+            _fut = _TOOL_EXECUTOR.submit(REGISTRY.call, tool_name, effective_args)
+            result = _fut.result(timeout=self._timeout_secs)
+        except _cf.TimeoutError:
+            if _fut is not None:
+                _fut.cancel()
+            log.error("Tool %r timed out after %ds", tool_name, self._timeout_secs)
+            self._audit.log_tool(
+                tool=tool_name, args=args, model=model_id, decision="timeout"
+            )
+            return ToolResult(
+                output="",
+                error=f"Tool {tool_name!r} timed out after {self._timeout_secs}s",
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.exception("Tool %r raised unexpectedly", tool_name)
+            self._audit.log_tool(
+                tool=tool_name, args=args, model=model_id, decision="error"
+            )
+            return ToolResult(output="", error=f"Tool {tool_name!r} raised: {exc}")
+
+        self._audit.log_tool(
+            tool=tool_name,
+            args=args,
+            model=model_id,
+            decision=str(decision),
+        )
+
+        # Invalidate cache on writes, then store on successful reads
+        if tool_name in _INVALIDATING_TOOLS:
+            path_arg = args.get("path") or args.get("file_path") or ""
+            if path_arg:
+                removed = _TOOL_CACHE.invalidate_path(path_arg)
+                log.debug("invalidated %d cache entries for %s", removed, path_arg)
+        elif result.ok:
+            _TOOL_CACHE.put(tool_name, args, result)
+            log.debug("cache stats: %s", _TOOL_CACHE.stats())
+
+        # Post-write hooks: invalidate FileCache + schedule CodeIndex re-index
+        # + append a structural diff snippet to the result output
+        if tool_name in _WRITE_TOOLS and result.ok:
+            self._post_write_hooks(tool_name, args)
+            path_arg = args.get("path") or args.get("file_path") or ""
+            if path_arg:
+                diff = self._structural_diff(path_arg)
+                if diff:
+                    result.output = (result.output or "") + "\n\n" + diff
+
+        return result
+
+    def _post_write_hooks(self, tool_name: str, args: dict[str, Any]) -> None:
+        """Invalidate file cache and trigger code re-index after a write tool."""
+        if not self._project_id or self._db is None:
+            return
+        path_arg = args.get("path") or args.get("file_path") or ""
+        if not path_arg:
+            return
+        from pathlib import Path
+        path = Path(path_arg)
+
+        try:
+            from src.memory.file_cache import FileCache
+            FileCache(self._db, self._project_id).invalidate(path)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("FileCache.invalidate failed for %s: %s", path_arg, exc)
+
+        try:
+            from src.memory.code_index import CodeIndex
+            from pathlib import Path as _Path
+            CodeIndex(db=self._db, project_id=self._project_id, project_root=_Path.cwd()).index_file(path)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("CodeIndex.index_file failed for %s: %s", path_arg, exc)
+
+    @staticmethod
+    def _structural_diff(path_str: str) -> str:
+        """Return a short diff snippet after a write, for context.
+
+        Tries difftastic (``difft``) first for semantic diffs; falls back to
+        ``git diff --stat HEAD <path>``. Returns empty string on any failure —
+        this is a best-effort display feature only.
+        """
+        import subprocess
+        from pathlib import Path
+
+        path = Path(path_str)
+        if not path.exists():
+            return ""
+
+        # Try difftastic — semantic, language-aware diff
+        try:
+            import shutil
+            if shutil.which("difft"):
+                r = subprocess.run(
+                    ["difft", "--color=never", path_str],
+                    capture_output=True, text=True, timeout=10,
+                )
+                if r.returncode == 0 and r.stdout.strip():
+                    lines = r.stdout.strip().splitlines()
+                    snippet = "\n".join(lines[:30])
+                    if len(lines) > 30:
+                        snippet += f"\n… ({len(lines) - 30} more lines)"
+                    return f"[difftastic]\n{snippet}"
+        except Exception:  # noqa: BLE001
+            pass
+
+        # Fallback: git diff --stat
+        try:
+            r = subprocess.run(
+                ["git", "diff", "--stat", "HEAD", "--", path_str],
+                capture_output=True, text=True, timeout=5,
+            )
+            if r.returncode == 0 and r.stdout.strip():
+                return f"[git diff --stat]\n{r.stdout.strip()[:500]}"
+        except Exception:  # noqa: BLE001
+            pass
+
+        return ""
+
+    def get_permitted_specs(self) -> list[dict[str, Any]]:
+        """Return OpenAI tool specs, excluding always-denied tools.
+
+        Permission enforcement happens at execute() time. This filters only
+        the hardcoded always-deny list to avoid advertising unusable tools.
+        Session-level denials are enforced at execution time to avoid
+        triggering interactive prompts during spec construction.
+
+        Returns:
+            List of OpenAI function spec dicts ready for the tools param.
+        """
+        return REGISTRY.openai_specs(exclude=_ALWAYS_DENY_TOOLS)
+
+    def register_plugin_tool(self, plugin_name: str, tool_schema: dict,
+                             ipc_channel: Any) -> None:
+        """Register a plugin tool — calls go through IPC, never in-process."""
+        tool_name = f"plugin.{plugin_name}.{tool_schema['name']}"
+        self._plugin_channels[tool_name] = (ipc_channel, tool_schema["name"])
+        log.info("Registered plugin tool: %s", tool_name)
+
+    def _dispatch_plugin(self, tool_name: str, args: dict) -> Any:
+        handle, raw_name = self._plugin_channels[tool_name]
+        resp = handle.call_tool(raw_name, args)
+        if "error" in resp:
+            raise RuntimeError(f"Plugin tool error: {resp['error']}")
+        return resp.get("result")
+
+    def dispatch_plugin(self, tool_name: str, args: dict) -> Any:
+        """Dispatch a registered plugin tool by its namespaced tool_name."""
+        if tool_name not in self._plugin_channels:
+            raise KeyError(f"Unknown plugin tool: {tool_name}")
+        return self._dispatch_plugin(tool_name, args)

src/agent/transcript.py

@@ -0,0 +1,230 @@
+"""TranscriptStore — in-memory sliding window of conversation turns.
+
+Mirrors the ClawCode architecture: two-layer memory where TranscriptStore
+holds the live session window and SessionStore persists it to disk.
+
+Design choices:
+  - Turns stored as plain dicts (matches OpenAI message format directly)
+  - token_count is always up-to-date (tracked incrementally, not recomputed)
+  - Oldest turns are evicted when budget is exceeded (compress first, then drop)
+  - No model calls here — pure data structure
+"""
+from __future__ import annotations
+
+import logging
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Iterator
+
+__all__ = ["Turn", "TranscriptStore"]
+
+log = logging.getLogger(__name__)
+
+# OpenAI role values
+Role = str  # "user" | "assistant" | "tool" | "system"
+
+
+@dataclass
+class Turn:
+    """A single conversation turn."""
+
+    role: Role
+    content: str
+    tokens: int = 0
+    tool_name: str | None = None    # set when role == "tool"
+    tool_call_id: str | None = None  # correlation between assistant call + tool result
+    tool_calls: list[dict] | None = None  # raw tool_calls list when role == "assistant"
+    non_droppable: bool = False       # if True, compression must preserve this turn verbatim
+    non_droppable_reason: str = ""    # human-readable reason (e.g. "unverified write: path.py")
+
+    def to_message(self) -> dict:  # type: ignore[type-arg]
+        """Serialise to OpenAI message dict (API-safe — no internal metadata)."""
+        msg: dict = {"role": self.role, "content": self.content}  # type: ignore[type-arg]
+        if self.tool_name:
+            msg["name"] = self.tool_name
+        if self.tool_call_id:
+            msg["tool_call_id"] = self.tool_call_id
+        if self.tool_calls is not None:
+            msg["tool_calls"] = self.tool_calls
+        return msg
+
+    def to_compress_dict(self) -> dict:  # type: ignore[type-arg]
+        """Serialise including compression metadata (non_droppable flag).
+
+        Used by _maybe_compress() when passing turns to the SessionCompressor.
+        NOT sent to the API — contains internal fields the API would reject.
+        """
+        d = self.to_message()
+        if self.non_droppable:
+            d["non_droppable"] = True
+        if self.non_droppable_reason:
+            d["non_droppable_reason"] = self.non_droppable_reason
+        return d
+
+    @classmethod
+    def from_message(cls, msg: dict, tokens: int = 0) -> Turn:  # type: ignore[type-arg]
+        return cls(
+            role=msg["role"],
+            content=msg.get("content") or "",
+            tokens=tokens,
+            tool_name=msg.get("name"),
+            tool_call_id=msg.get("tool_call_id"),
+            tool_calls=msg.get("tool_calls"),
+        )
+
+    @classmethod
+    def assistant_with_tool_calls(
+        cls,
+        tool_calls: list[dict],  # type: ignore[type-arg]
+        tokens: int = 0,
+    ) -> Turn:
+        """Build an assistant turn that carries tool_calls but no content."""
+        return cls(role="assistant", content="", tokens=tokens, tool_calls=tool_calls)
+
+
+class TranscriptStore:
+    """In-memory sliding window of conversation turns with token tracking.
+
+    Usage::
+
+        store = TranscriptStore(max_tokens=120_000)
+        store.append(Turn(role="user", content="Fix the auth bug", tokens=8))
+        store.append(Turn(role="assistant", content="...", tokens=412))
+        messages = store.to_messages()  # ready for API call
+    """
+
+    def __init__(self, max_tokens: int = 120_000) -> None:
+        self._turns: deque[Turn] = deque()
+        self._max_tokens = max_tokens
+        self._total_tokens: int = 0
+
+    # ------------------------------------------------------------------
+    # Core API
+    # ------------------------------------------------------------------
+
+    def append(self, turn: Turn) -> None:
+        """Add a turn. Does NOT evict — call maybe_evict() separately."""
+        self._turns.append(turn)
+        self._total_tokens += turn.tokens
+
+    def prepend_system(self, content: str, tokens: int = 0) -> None:
+        """Insert / replace a system turn at position 0."""
+        if self._turns and self._turns[0].role == "system":
+            old = self._turns[0]
+            self._total_tokens -= old.tokens
+            self._turns[0] = Turn(role="system", content=content, tokens=tokens)
+        else:
+            self._turns.appendleft(Turn(role="system", content=content, tokens=tokens))
+        self._total_tokens += tokens
+
+    def maybe_evict(self, budget_tokens: int | None = None) -> int:
+        """Evict oldest non-system turns until under budget. Returns evicted count."""
+        limit = budget_tokens or self._max_tokens
+        evicted = 0
+        while self._total_tokens > limit and len(self._turns) > 1:
+            removed = self.evict_oldest(keep_system=True)
+            if removed is None:
+                break
+            evicted += 1
+        return evicted
+
+    def evict_oldest(self, keep_system: bool = True) -> Turn | None:
+        """Evict the oldest evictable turn (or block). Returns it or None.
+
+        If the oldest evictable turn is an assistant turn with tool_calls,
+        it evicts that turn AND all immediately following tool-result turns
+        that correlate with it — keeping the message history valid.
+        """
+        turns_list = list(self._turns)
+        for i, turn in enumerate(turns_list):
+            if keep_system and turn.role == "system":
+                continue
+
+            # Gather indices to evict (at minimum: [i])
+            to_evict = [i]
+
+            # If this is an assistant turn with tool_calls, also evict
+            # all immediately following tool-result turns belonging to it.
+            if turn.tool_calls:
+                call_ids = {tc.get("id") for tc in turn.tool_calls if tc.get("id")}
+                j = i + 1
+                while j < len(turns_list):
+                    nxt = turns_list[j]
+                    if nxt.role == "tool" and nxt.tool_call_id in call_ids:
+                        to_evict.append(j)
+                        j += 1
+                    else:
+                        break
+
+            # Remove from high to low index to preserve indices
+            for idx in reversed(to_evict):
+                self._total_tokens -= turns_list[idx].tokens
+            remaining = [t for idx_t, t in enumerate(turns_list) if idx_t not in set(to_evict)]
+            self._turns = deque(remaining)
+            return turns_list[i]
+
+        return None
+
+    def replace_oldest_tool_results(self, summary: str, summary_tokens: int) -> int:
+        """Compress oldest tool results into a one-line summary. Returns count replaced."""
+        replaced = 0
+        for i, turn in enumerate(self._turns):
+            if turn.role == "tool" and turn.tokens > 200:
+                self._total_tokens -= turn.tokens
+                turns_list = list(self._turns)
+                turns_list[i] = Turn(
+                    role="tool",
+                    content=summary,
+                    tokens=summary_tokens,
+                    tool_name=turn.tool_name,
+                    tool_call_id=turn.tool_call_id,
+                )
+                self._turns = deque(turns_list)
+                self._total_tokens += summary_tokens
+                replaced += 1
+                if self._total_tokens <= self._max_tokens:
+                    break
+        return replaced
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_messages(self) -> list[dict]:  # type: ignore[type-arg]
+        """Return turns as a list of OpenAI message dicts."""
+        return [t.to_message() for t in self._turns]
+
+    def to_turns(self) -> list[Turn]:
+        """Return a snapshot of all turns."""
+        return list(self._turns)
+
+    @classmethod
+    def from_turns(cls, turns: list[Turn], max_tokens: int = 120_000) -> TranscriptStore:
+        """Reconstruct from a persisted turn list."""
+        store = cls(max_tokens=max_tokens)
+        for turn in turns:
+            store.append(turn)
+        return store
+
+    # ------------------------------------------------------------------
+    # Introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def token_count(self) -> int:
+        return self._total_tokens
+
+    @property
+    def turn_count(self) -> int:
+        return len(self._turns)
+
+    @property
+    def budget_ratio(self) -> float:
+        """Fraction of max_tokens used (0.0–1.0+)."""
+        return self._total_tokens / self._max_tokens if self._max_tokens else 0.0
+
+    def __iter__(self) -> Iterator[Turn]:
+        return iter(self._turns)
+
+    def __len__(self) -> int:
+        return len(self._turns)