monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/types/interfaces.py

@@ -0,0 +1,156 @@
+"""Shared interfaces for monkeybot agent components.
+
+This module defines interfaces and data structures used across the project.
+The default **SSE gateway** path uses native :class:`~monkeybot.core.llm.provider.Provider`
+implementations and SQLite-backed history rather than a separate graph-based
+orchestration runtime.
+
+Remaining interfaces support backward compatibility.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+# ============================================================================
+# Data Classes
+# ============================================================================
+
+
+@dataclass
+class Message:
+    """Conversation message.
+
+    Attributes:
+        role: Message role ("user", "assistant", or "system")
+        content: Message text content
+        timestamp: ISO8601 timestamp when message was created
+        trace_id: Request trace ID for debugging and log correlation
+    """
+
+    role: str
+    content: str
+    timestamp: str
+    trace_id: str
+
+
+@dataclass
+class ExecutionResult:
+    """Result from terminal command execution.
+
+    Attributes:
+        stdout: Standard output from command
+        stderr: Standard error from command
+        exit_code: Process exit code (0 = success, non-zero = error)
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+# ============================================================================
+# Exceptions
+# ============================================================================
+
+
+class MonkeybotError(Exception):
+    """Base exception for all Monkeybot errors.
+
+    All custom exceptions in Monkeybot inherit from this base class.
+    This allows catching all Monkeybot-specific errors with a single except clause.
+    """
+
+    pass
+
+
+class AgentError(MonkeybotError):
+    """Raised when agent processing fails.
+
+    Examples:
+        - LLM call fails
+        - Message processing fails
+        - Graph execution error
+    """
+
+    pass
+
+
+class LLMError(MonkeybotError):
+    """Raised when LLM API call fails.
+
+    Examples:
+        - Vertex AI timeout
+        - Rate limit exceeded (429)
+        - Model unavailable (503)
+        - Invalid API credentials
+        
+    Note: Provider-level LLM errors are handled by the streaming adapter; this
+    exception is kept for explicit error handling when needed.
+    """
+
+    pass
+
+
+class SecurityError(MonkeybotError):
+    """Raised when security validation fails.
+
+    Examples:
+        - Command not in ALLOWED_COMMANDS
+        - Path not in ALLOWED_PATHS
+        - Unauthorized user access attempt
+
+    This is a critical security boundary - all SecurityErrors should be logged
+    and investigated.
+    """
+
+    pass
+
+
+# ============================================================================
+# Agent Core Interface (for Gateway compatibility)
+# ============================================================================
+
+
+class AgentCoreInterface(ABC):
+    """Contract that Gateway calls.
+
+    This interface defines how external components (Gateway) interact with
+    the agent. Implemented by AgentWrapper in src/core/agent.py.
+
+    Key responsibilities:
+        - Process user messages
+        - Maintain conversation context (implementation-specific storage)
+        - Execute tools/skills
+        - Return formatted responses
+    """
+
+    @abstractmethod
+    async def process_message(self, user_id: str, content: str, trace_id: str) -> str:
+        """Process user message and return response.
+
+        This is the main entry point for all user interactions. The Gateway
+        filters PII before calling this method, so user_id is already hashed
+        and content contains only safe user input.
+
+        Args:
+            user_id: Hashed user identifier (NOT email - already filtered by Gateway)
+            content: Message text (PII already filtered by Gateway)
+            trace_id: Request trace ID for debugging and log correlation
+
+        Returns:
+            Response text to send back to user via Gateway
+
+        Raises:
+            AgentError: If processing fails (LLM error, tool error, etc.)
+
+        Example:
+            >>> agent = build_agent(model, tools)
+            >>> response = await agent.process_message(
+            ...     user_id="abc123",
+            ...     content="What can you help me with?",
+            ...     trace_id="trace_xyz"
+            ... )
+            >>> print(response)
+            "I can help you with..."
+        """
+        pass

monkeybot/core/types/types_tools.py

@@ -0,0 +1,29 @@
+"""Shared tool definitions for the v2 harness.
+
+`ToolDef` is referenced by ``monkeybot.core.llm.provider`` and MCP/context layers per
+architecture docs; defining it once avoids import cycles across those modules.
+
+See Story 2 ``types_tools`` task for canonical fields.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ToolDef:
+    """Tool schema surfaced to providers (JSON-schema ``input_schema``).
+
+    ``parallel_safe`` marks read-only (or otherwise concurrent-safe) tools that
+    the harness may execute together in one batch. Mutating tools stay serial
+    unless explicitly opted in. Providers ignore this field.
+
+    ``doom_loop_exempt`` skips the identical name+args doom-loop guard for tools
+    that are expected to repeat with the same arguments (e.g. ``loop_status``
+    polling). Providers ignore this field.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, object]
+    parallel_safe: bool = False
+    doom_loop_exempt: bool = False

monkeybot/core/workspace/__init__.py

@@ -0,0 +1,8 @@
+"""Pluggable workspace storage (memory tree backends)."""
+
+from __future__ import annotations
+
+from monkeybot.core.workspace.factory import create_workspace_storage
+from monkeybot.core.workspace.protocol import WorkspaceStorage
+
+__all__ = ["WorkspaceStorage", "create_workspace_storage"]

monkeybot/core/workspace/factory.py

@@ -0,0 +1,45 @@
+"""Factory for :class:`~monkeybot.core.workspace.protocol.WorkspaceStorage` from a URI string."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from monkeybot.core.workspace.local import LocalWorkspaceStorage
+from monkeybot.core.workspace.protocol import WorkspaceStorage
+
+
+def _bucket_and_prefix(scheme_body: str) -> tuple[str, str]:
+    body = scheme_body.strip().lstrip("/")
+    if not body:
+        raise ValueError("URI must include a bucket name")
+    bucket, _, prefix = body.partition("/")
+    return bucket.strip(), prefix.strip().strip("/")
+
+
+def create_workspace_storage(uri: str) -> WorkspaceStorage:
+    """Return storage for ``local://``, ``gcs://``, ``s3://``, or a bare filesystem path.
+
+    Lazy-imports optional cloud SDKs so local-only installs pay no import cost.
+    """
+    u = uri.strip()
+    if not u:
+        raise ValueError("workspace storage URI is empty")
+
+    if u.startswith("gcs://"):
+        from monkeybot.core.workspace.gcs import GCSWorkspaceStorage
+
+        bucket, prefix = _bucket_and_prefix(u[len("gcs://") :])
+        return GCSWorkspaceStorage(bucket=bucket, prefix=prefix)
+
+    if u.startswith("s3://"):
+        from monkeybot.core.workspace.s3 import S3WorkspaceStorage
+
+        bucket, prefix = _bucket_and_prefix(u[len("s3://") :])
+        return S3WorkspaceStorage(bucket=bucket, prefix=prefix)
+
+    path_str = u.removeprefix("local://").strip()
+    root = Path(path_str).expanduser()
+    return LocalWorkspaceStorage(root)
+
+
+__all__ = ["create_workspace_storage"]

monkeybot/core/workspace/gcs.py

@@ -0,0 +1,130 @@
+"""Google Cloud Storage :class:`WorkspaceStorage` (``google-cloud-storage``)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from google.cloud.exceptions import NotFound
+
+from monkeybot.core.workspace.protocol import WorkspaceStorage
+
+_log = logging.getLogger(__name__)
+
+
+class GCSWorkspaceStorage:
+    """Object-prefix layout: ``gs://bucket/{prefix}/{path}``."""
+
+    def __init__(self, bucket: str, prefix: str = "") -> None:
+        from google.cloud.storage import Client
+
+        self._client = Client()
+        self._bucket = self._client.bucket(bucket)
+        self._prefix = prefix.strip().strip("/").replace("\\", "/")
+        if self._prefix:
+            self._prefix = self._prefix + "/"
+
+    def _key(self, path: str) -> str:
+        key = path.strip().replace("\\", "/").lstrip("/")
+        return self._prefix + key if self._prefix else key
+
+    async def read_text(self, path: str) -> str:
+        key = self._key(path)
+
+        def _read() -> str:
+            blob = self._bucket.blob(key)
+            data = blob.download_as_bytes()
+            text: str = data.decode("utf-8")
+            return text
+
+        try:
+            return await asyncio.to_thread(_read)
+        except NotFound as exc:
+            raise FileNotFoundError(key) from exc
+
+    async def write_text(self, path: str, content: str) -> None:
+        key = self._key(path)
+
+        def _write() -> None:
+            blob = self._bucket.blob(key)
+            blob.upload_from_string(content, content_type="text/plain; charset=utf-8")
+
+        await asyncio.to_thread(_write)
+
+    async def append_text(self, path: str, content: str) -> None:
+        key = self._key(path)
+        blob = self._bucket.blob(key)
+
+        def _append() -> None:
+            try:
+                cur = blob.download_as_text(encoding="utf-8")
+            except NotFound:
+                cur = ""
+            blob.upload_from_string(cur + content, content_type="text/plain; charset=utf-8")
+
+        await asyncio.to_thread(_append)
+
+    async def exists(self, path: str) -> bool:
+        key = self._key(path)
+
+        def _exists() -> bool:
+            return bool(self._bucket.blob(key).exists())
+
+        return await asyncio.to_thread(_exists)
+
+    async def list_files(self, prefix: str = "") -> list[str]:
+        pfx = self._key(prefix).rstrip("/")
+        if pfx:
+            pfx = pfx + "/"
+
+        def _list() -> list[str]:
+            out: list[str] = []
+            for blob in self._client.list_blobs(self._bucket.name, prefix=pfx):
+                name = blob.name
+                if name.endswith("/"):
+                    continue
+                rel = name[len(self._prefix) :] if self._prefix else name
+                out.append(rel.lstrip("/"))
+            return sorted(out)
+
+        return await asyncio.to_thread(_list)
+
+    async def delete(self, path: str) -> None:
+        key = self._key(path)
+
+        def _del() -> None:
+            self._bucket.blob(key).delete()
+
+        try:
+            await asyncio.to_thread(_del)
+        except NotFound:
+            return
+
+    async def move(self, src: str, dest: str) -> None:
+        sk = self._key(src)
+        dk = self._key(dest)
+        sb = self._bucket.blob(sk)
+        db = self._bucket.blob(dk)
+
+        def _copy() -> None:
+            rewrite_token = None
+            while True:
+                rewrite_token, _, _ = db.rewrite(sb, token=rewrite_token)
+                if rewrite_token is None:
+                    break
+
+        await asyncio.to_thread(_copy)
+        try:
+            await asyncio.to_thread(sb.delete)
+        except Exception as exc:
+            _log.warning("gcs move: delete source failed after copy src=%s dest=%s: %r", sk, dk, exc)
+
+    async def gc_prefix(self, prefix: str, max_age_sec: float) -> dict[str, int]:
+        del prefix, max_age_sec
+        _log.info(
+            "gcs gc_prefix: skipped — configure object lifecycle rules on the bucket for prefix cleanup"
+        )
+        return {"scanned": 0, "deleted": 0, "errors": 0}
+
+
+__all__ = ["GCSWorkspaceStorage"]

monkeybot/core/workspace/local.py

@@ -0,0 +1,162 @@
+"""Local filesystem :class:`WorkspaceStorage` (zero extra dependencies)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+import time
+from pathlib import Path
+
+from monkeybot.core.workspace.protocol import WorkspaceStorage
+
+_log = logging.getLogger(__name__)
+
+
+def _posix_rel(root: Path, path: Path) -> str:
+    rel = path.resolve().relative_to(root.resolve())
+    return rel.as_posix()
+
+
+class LocalWorkspaceStorage:
+    """``pathlib``-backed storage; blocking I/O runs in ``asyncio.to_thread``."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = Path(root).expanduser().resolve()
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def _abs(self, path: str) -> Path:
+        key = path.strip().replace("\\", "/").lstrip("/")
+        return (self._root / key).resolve()
+
+    def _ensure_under_root(self, path: Path) -> None:
+        path.relative_to(self._root)
+
+    async def read_text(self, path: str) -> str:
+        p = self._abs(path)
+        self._ensure_under_root(p)
+
+        def _read() -> str:
+            if not p.is_file():
+                raise FileNotFoundError(str(p))
+            return p.read_text(encoding="utf-8")
+
+        return await asyncio.to_thread(_read)
+
+    async def write_text(self, path: str, content: str) -> None:
+        p = self._abs(path)
+        self._ensure_under_root(p)
+
+        def _write() -> None:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(content, encoding="utf-8")
+
+        await asyncio.to_thread(_write)
+
+    async def append_text(self, path: str, content: str) -> None:
+        p = self._abs(path)
+        self._ensure_under_root(p)
+
+        def _append() -> None:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            with p.open("a", encoding="utf-8") as fh:
+                fh.write(content)
+
+        await asyncio.to_thread(_append)
+
+    async def exists(self, path: str) -> bool:
+        p = self._abs(path)
+        self._ensure_under_root(p)
+
+        def _exists() -> bool:
+            return p.is_file()
+
+        return await asyncio.to_thread(_exists)
+
+    async def list_files(self, prefix: str = "") -> list[str]:
+        root = self._root
+        pre = prefix.strip().replace("\\", "/")
+        if pre and not pre.endswith("/"):
+            pre = pre + "/"
+
+        def _list() -> list[str]:
+            base = root if not pre else (root / pre).resolve()
+            if not base.exists():
+                return []
+            self._ensure_under_root(base)
+            out: list[str] = []
+            for path in sorted(base.rglob("*")):
+                if not path.is_file():
+                    continue
+                try:
+                    rel = _posix_rel(root, path)
+                except ValueError:
+                    continue
+                out.append(rel)
+            return out
+
+        return await asyncio.to_thread(_list)
+
+    async def delete(self, path: str) -> None:
+        p = self._abs(path)
+        self._ensure_under_root(p)
+
+        def _unlink() -> None:
+            try:
+                p.unlink(missing_ok=True)
+            except OSError as exc:
+                _log.warning("delete failed for %s: %r", p, exc)
+
+        await asyncio.to_thread(_unlink)
+
+    async def move(self, src: str, dest: str) -> None:
+        sp = self._abs(src)
+        dp = self._abs(dest)
+        self._ensure_under_root(sp)
+        self._ensure_under_root(dp)
+
+        def _mv() -> None:
+            dp.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                sp.replace(dp)
+            except OSError:
+                shutil.move(str(sp), str(dp))
+
+        await asyncio.to_thread(_mv)
+
+    async def gc_prefix(self, prefix: str, max_age_sec: float) -> dict[str, int]:
+        root = self._root
+        pre = prefix.strip().replace("\\", "/")
+        if pre and not pre.endswith("/"):
+            pre = pre + "/"
+        cutoff = time.time() - float(max_age_sec)
+
+        def _sweep() -> dict[str, int]:
+            counts = {"scanned": 0, "deleted": 0, "errors": 0}
+            base = root if not pre else (root / pre).resolve()
+            if not base.exists():
+                return counts
+            try:
+                base.relative_to(root.resolve())
+            except ValueError:
+                return counts
+            for path in sorted(base.rglob("*")):
+                if not path.is_file():
+                    continue
+                counts["scanned"] += 1
+                try:
+                    if path.stat().st_mtime < cutoff:
+                        path.unlink()
+                        counts["deleted"] += 1
+                except OSError:
+                    counts["errors"] += 1
+                    _log.debug("gc_prefix: skip %s", path.name)
+            return counts
+
+        return await asyncio.to_thread(_sweep)
+
+
+__all__ = ["LocalWorkspaceStorage"]

monkeybot/core/workspace/protocol.py

@@ -0,0 +1,45 @@
+"""Pluggable workspace storage for durable markdown memory (local FS, GCS, S3)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WorkspaceStorage(Protocol):
+    """Async key-value file storage under a logical root (memory tree).
+
+    Paths are always POSIX-style relative keys (e.g. ``raw/foo.md``, ``INDEX.md``).
+    Implementations must not require a running event loop at import time.
+    """
+
+    async def read_text(self, path: str) -> str:
+        """Read UTF-8 text; raise ``FileNotFoundError`` if missing."""
+
+    async def write_text(self, path: str, content: str) -> None:
+        """Write or replace file at ``path`` (parent prefixes created as needed)."""
+
+    async def append_text(self, path: str, content: str) -> None:
+        """Append ``content`` to ``path`` (create file if absent)."""
+
+    async def exists(self, path: str) -> bool:
+        """Return whether ``path`` exists as a file."""
+
+    async def list_files(self, prefix: str = "") -> list[str]:
+        """List all file paths under ``prefix``, recursive, POSIX relative paths."""
+
+    async def delete(self, path: str) -> None:
+        """Delete file at ``path`` if it exists (ignore missing)."""
+
+    async def move(self, src: str, dest: str) -> None:
+        """Move/rename ``src`` to ``dest`` (atomic when the backend allows)."""
+
+    async def gc_prefix(self, prefix: str, max_age_sec: float) -> dict[str, int]:
+        """Best-effort GC of files under ``prefix`` older than ``max_age_sec``.
+
+        Returns ``{"scanned": int, "deleted": int, "errors": int}``.
+        Cloud backends may return zeros and rely on bucket lifecycle rules.
+        """
+
+
+__all__ = ["WorkspaceStorage"]