agentshive-sdk 0.2.0__py3-none-any.whl

agentshive/__init__.py

@@ -0,0 +1,3 @@
+from agentshive.client import BackendClient, AgentClient
+from agentshive.models import Attachment, Message, Task
+__all__ = ["BackendClient", "AgentClient", "Message", "Attachment", "Task"]

agentshive/api.py

@@ -0,0 +1,352 @@
+"""REST client for the AgentsHive server API."""
+from __future__ import annotations
+
+import json
+import logging
+import mimetypes
+from pathlib import Path
+
+import httpx
+
+from agentshive.backends.base import IMAGE_EXTENSIONS
+from agentshive.models import Message
+
+logger = logging.getLogger(__name__)
+
+# Fallback MIME types for extensions that mimetypes may not know.
+_MIME_FALLBACK = {
+    ".apng": "image/apng",
+    ".avif": "image/avif",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+}
+
+
+def _mime_from_ext(ext: str) -> str:
+    """Derive MIME type from extension. Only allows extensions in IMAGE_EXTENSIONS."""
+    if ext not in IMAGE_EXTENSIONS:
+        return "application/octet-stream"
+    mime, _ = mimetypes.guess_type(f"file{ext}")
+    return mime or _MIME_FALLBACK.get(ext, "application/octet-stream")
+
+
+class AgentAPI:
+    """Async REST client for the AgentsHive server API.
+
+    Used internally by :class:`~agenthive.client.BackendClient` and also
+    available directly via ``client.api`` for custom API calls.
+    """
+
+    def __init__(self, server_url: str, token: str):
+        """Create a new API client.
+
+        Args:
+            server_url: Base URL of the AgentsHive server.
+            token: Backend machine token (``ahv_...``).
+        """
+        self._base = server_url.rstrip("/")
+        self._headers = {"Authorization": f"Bearer {token}"}
+        self._client = httpx.AsyncClient(base_url=self._base, headers=self._headers, timeout=30.0)
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        """Issue an HTTP request with debug logging."""
+        logger.debug("API %s %s", method, path)
+        resp = await self._client.request(method, path, **kwargs)
+        logger.debug("API %s %s -> %d (%d bytes)", method, path, resp.status_code, len(resp.content))
+        return resp
+
+    async def get_me(self) -> dict:
+        """Return the authenticated backend machine's metadata."""
+        resp = await self._request("GET", "/api/backends/me")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_tasks(self, status: str = "queued") -> list[dict]:
+        """List tasks assigned to this backend, filtered by status."""
+        resp = await self._request("GET", "/api/backends/me/tasks", params={"status": status})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def ack_task(self, task_id: str) -> dict:
+        """Acknowledge a task (transition from queued to processing)."""
+        resp = await self._request("POST", f"/api/backends/me/tasks/{task_id}/ack")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def complete_task(self, task_id: str) -> dict:
+        """Mark a task as successfully completed."""
+        resp = await self._request("POST", f"/api/backends/me/tasks/{task_id}/complete")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def fail_task(self, task_id: str, error: str = "") -> dict:
+        """Mark a task as failed with an optional error message."""
+        resp = await self._request("POST", f"/api/backends/me/tasks/{task_id}/fail", json={"error": error})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_messages(self, thread_id: str, limit: int = 50, after: str | None = None) -> list[Message]:
+        """Fetch messages from a thread, most recent last.
+
+        Args:
+            thread_id: Thread to fetch messages from.
+            limit: Maximum number of messages to return.
+            after: Only return messages created after this message ID.
+        """
+        params = {}
+        if after:
+            params["after"] = after
+        resp = await self._request("GET", f"/api/threads/{thread_id}/messages", params=params)
+        resp.raise_for_status()
+        return [Message.from_dict(m, api=self) for m in resp.json()[-limit:]]
+
+    async def post_message(self, thread_id: str, text: str, agent_handle: str = "", mentions: list[str] | None = None, quoted_message_id: str | None = None, task_id: str | None = None) -> Message | None:
+        """Post a message to a thread on behalf of an agent.
+
+        Args:
+            thread_id: Target thread.
+            text: Message body (supports markdown).
+            agent_handle: The agent posting this message.
+            mentions: Explicit @mentions to include (triggers those agents).
+            quoted_message_id: ID of a message to quote.
+            task_id: The dispatch task this reply is for (links message to batch).
+        """
+        data = {"text": text}
+        if agent_handle:
+            data["agent_handle"] = agent_handle
+        if mentions:
+            data["explicit_mentions"] = json.dumps(mentions)
+        if quoted_message_id:
+            data["quoted_message_id"] = quoted_message_id
+        if task_id:
+            data["task_id"] = task_id
+        resp = await self._request("POST", f"/api/threads/{thread_id}/messages", data=data)
+        resp.raise_for_status()
+        body = resp.json()
+        # Server may filter non-substantive agent replies (soft-PASSes)
+        if body.get("filtered"):
+            return None
+        return Message.from_dict(body, api=self)
+
+    async def post_message_with_files(
+        self,
+        thread_id: str,
+        text: str,
+        file_paths: list[str],
+        agent_handle: str = "",
+        mentions: list[str] | None = None,
+        quoted_message_id: str | None = None,
+        task_id: str | None = None,
+    ) -> Message | None:
+        """Post a message with file attachments (multipart upload).
+
+        Args:
+            thread_id: Target thread.
+            text: Message body.
+            file_paths: Local file paths to upload as attachments.
+            agent_handle: The agent posting this message.
+            mentions: Explicit @mentions to include.
+            quoted_message_id: ID of a message to quote.
+            task_id: The dispatch task this reply is for.
+        """
+        data = {"text": text}
+        if agent_handle:
+            data["agent_handle"] = agent_handle
+        if mentions:
+            data["explicit_mentions"] = json.dumps(mentions)
+        if quoted_message_id:
+            data["quoted_message_id"] = quoted_message_id
+        if task_id:
+            data["task_id"] = task_id
+
+        files = []
+        open_handles = []
+        try:
+            for fp in file_paths:
+                p = Path(fp)
+                if not p.exists():
+                    logger.warning("Skipping missing file: %s", fp)
+                    continue
+                fh = open(p, "rb")  # noqa: SIM115
+                open_handles.append(fh)
+                # httpx expects (field_name, (filename, file_obj, content_type))
+                mime = _mime_from_ext(p.suffix.lower())
+                files.append(("files", (p.name, fh, mime)))
+
+            resp = await self._request(
+                "POST",
+                f"/api/threads/{thread_id}/messages",
+                data=data,
+                files=files,
+                timeout=60.0,
+            )
+            resp.raise_for_status()
+            body = resp.json()
+            if body.get("filtered"):
+                return None
+            return Message.from_dict(body, api=self)
+        finally:
+            for fh in open_handles:
+                fh.close()
+
+    # ------------------------------------------------------------------
+    # Memory endpoints
+    # ------------------------------------------------------------------
+
+    async def save_memories(
+        self,
+        memories: list[dict],
+        space_id: str = "",
+        thread_id: str = "",
+        agent_handle: str = "",
+        corrections: list[dict] | None = None,
+        participants: list[str] | None = None,
+    ) -> dict:
+        """Persist extracted memories and corrections to the server."""
+        logger.info("Saving %d memories, %d corrections for @%s", len(memories), len(corrections or []), agent_handle)
+        body: dict = {
+            "memories": memories, "space_id": space_id, "thread_id": thread_id,
+        }
+        if agent_handle:
+            body["agent_handle"] = agent_handle
+        if corrections:
+            body["corrections"] = corrections
+        if participants:
+            body["participants"] = participants
+        resp = await self._request("POST", "/api/backends/me/memories", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_memory_context(self, space_id: str = "", participants: list[str] | None = None, agent_handle: str = "") -> tuple[str, str]:
+        """Fetch formatted memory context and project rules for prompt injection.
+
+        Returns:
+            (memory_context, space_rules) tuple.
+        """
+        logger.info("Fetching memory context for @%s (space=%s)", agent_handle, space_id[:8])
+        params: dict[str, str] = {"space_id": space_id}
+        if participants:
+            params["participants"] = ",".join(participants)
+        if agent_handle:
+            params["agent_handle"] = agent_handle
+        resp = await self._request("GET", "/api/backends/me/memories", params=params)
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("context", ""), data.get("space_rules", "")
+
+    # ------------------------------------------------------------------
+    # Artifact endpoints
+    # ------------------------------------------------------------------
+
+    async def list_artifacts(self, thread_id: str) -> list[dict]:
+        """List artifacts in a thread."""
+        resp = await self._request("GET", f"/api/threads/{thread_id}/artifacts")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_artifact(
+        self,
+        thread_id: str,
+        title: str,
+        content: str,
+        content_type: str = "markdown",
+        *,
+        author_handle: str = "",
+        author_display_name: str = "",
+        message_id: str | None = None,
+        status: str = "draft",
+    ) -> dict:
+        """Create an artifact in a thread.
+
+        Args:
+            thread_id: Thread to attach the artifact to.
+            title: Display title.
+            content: Artifact body.
+            content_type: One of markdown, code, html, mermaid.
+            author_handle: Agent handle creating this artifact.
+            author_display_name: Agent display name.
+            message_id: Optional message to link the artifact to.
+            status: draft or published.
+        """
+        body = {
+            "thread_id": thread_id,
+            "title": title,
+            "content": content,
+            "content_type": content_type,
+            "author_handle": author_handle,
+            "author_display_name": author_display_name,
+            "status": status,
+        }
+        if message_id:
+            body["message_id"] = message_id
+        resp = await self._request("POST", "/api/artifacts", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def update_artifact(
+        self,
+        artifact_id: str,
+        content: str,
+        *,
+        author_handle: str = "",
+        summary: str = "",
+    ) -> dict:
+        """Update an artifact's content (creates a new version).
+
+        Args:
+            artifact_id: Artifact to update.
+            content: New content.
+            author_handle: Agent handle making the update.
+            summary: Optional change summary.
+        """
+        body = {
+            "content": content,
+            "author_handle": author_handle,
+            "summary": summary,
+        }
+        resp = await self._request("PUT", f"/api/artifacts/{artifact_id}", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_artifact_comment(
+        self,
+        artifact_id: str,
+        text: str,
+        *,
+        author_handle: str = "",
+        author_display_name: str = "",
+        role: str = "agent",
+    ) -> dict:
+        """Add a comment to an artifact.
+
+        Args:
+            artifact_id: Artifact to comment on.
+            text: Comment text (supports @mentions).
+            author_handle: Agent handle posting the comment.
+            author_display_name: Agent display name.
+            role: Comment role (agent or human).
+        """
+        body = {
+            "text": text,
+            "author_handle": author_handle,
+            "author_display_name": author_display_name,
+            "role": role,
+        }
+        resp = await self._request("POST", f"/api/artifacts/{artifact_id}/comments", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Stats endpoint
+    # ------------------------------------------------------------------
+
+    async def report_stats(self, stats: dict) -> dict:
+        """Report token usage / invocation stats to the server."""
+        logger.info("Reporting stats: %d input, %d output tokens", stats.get("input_tokens", 0), stats.get("output_tokens", 0))
+        resp = await self._request("POST", "/api/backends/me/stats", json=stats)
+        resp.raise_for_status()
+        return resp.json()

agentshive/backends/__init__.py

@@ -0,0 +1,30 @@
+"""Per-backend module structure for local CLI agents."""
+
+from .registry import register, create_backend, is_available, list_available, list_all
+from .base import LocalCliBackend, LocalInvocationResult
+from .claude_code import LocalClaudeCodeBackend
+from .gemini_cli import LocalGeminiCliBackend
+from .codex_cli import LocalCodexCliBackend
+from .openclaw import LocalOpenClawBackend
+from .opencode import LocalOpenCodeBackend
+
+register("claude_code", LocalClaudeCodeBackend)
+register("gemini_cli", LocalGeminiCliBackend)
+register("codex", LocalCodexCliBackend)
+register("openclaw", LocalOpenClawBackend)
+register("opencode", LocalOpenCodeBackend)
+
+__all__ = [
+    "register",
+    "create_backend",
+    "is_available",
+    "list_available",
+    "list_all",
+    "LocalCliBackend",
+    "LocalInvocationResult",
+    "LocalClaudeCodeBackend",
+    "LocalGeminiCliBackend",
+    "LocalCodexCliBackend",
+    "LocalOpenClawBackend",
+    "LocalOpenCodeBackend",
+]

agentshive/backends/base.py

@@ -0,0 +1,207 @@
+"""Base class and result dataclass for local CLI backends."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Image extensions we detect as generated files.
+# SVG excluded — can contain <script> tags (XSS vector).
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".apng", ".avif", ".heic", ".heif"}
+
+# Max depth for recursive image file scanning.
+_MAX_SCAN_DEPTH = 3
+# Max file size for upload (20 MB).
+MAX_GENERATED_FILE_BYTES = 20 * 1024 * 1024
+
+
+@dataclass
+class LocalInvocationResult:
+    """Structured result from a local CLI invocation."""
+
+    text: str
+    session_id: str | None = None
+    stop_reason: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cost_usd: float = 0.0
+    generated_files: list[str] = field(default_factory=list)
+
+
+class LocalCliBackend(ABC):
+    """Abstract base for CLI-backed agents.
+
+    Subclasses must implement :meth:`is_available`, :meth:`_base_command`,
+    :meth:`_build_args`, and :meth:`_parse_output`.
+    """
+
+    supports_resume: bool = False
+
+    @classmethod
+    @abstractmethod
+    def is_available(cls) -> bool:
+        """Return True when the required CLI binary is on PATH."""
+        ...
+
+    @abstractmethod
+    def _base_command(self) -> list[str]:
+        """Return the base CLI command tokens (no resume flags)."""
+        ...
+
+    @abstractmethod
+    def _build_args(self, session_id: str | None = None) -> list[str]:
+        """Return the full command list, optionally with resume flags."""
+        ...
+
+    @abstractmethod
+    def _parse_output(self, stdout: str) -> LocalInvocationResult:
+        """Parse CLI stdout into a structured result."""
+        ...
+
+    def _get_stdin_data(self, prompt: str) -> str | None:
+        """Return data to pipe to stdin, or None."""
+        return prompt
+
+    def _snapshot_image_files(self, cwd: str | None) -> dict[str, float]:
+        """Return {resolved_path: mtime} for image files under cwd (bounded depth)."""
+        if not cwd:
+            return {}
+        cwd_resolved = Path(cwd).resolve()
+        result: dict[str, float] = {}
+        self._scan_dir(cwd_resolved, cwd_resolved, 0, result)
+        return result
+
+    def _scan_dir(
+        self, directory: Path, cwd_root: Path, depth: int, out: dict[str, float]
+    ) -> None:
+        """Recursively scan for image files up to _MAX_SCAN_DEPTH."""
+        if depth > _MAX_SCAN_DEPTH:
+            return
+        try:
+            for entry in os.scandir(directory):
+                if entry.is_dir(follow_symlinks=False) and not entry.name.startswith("."):
+                    self._scan_dir(Path(entry.path), cwd_root, depth + 1, out)
+                elif entry.is_file(follow_symlinks=False) and Path(entry.name).suffix.lower() in IMAGE_EXTENSIONS:
+                    resolved = Path(entry.path).resolve()
+                    # Guard against symlink exfiltration
+                    if not str(resolved).startswith(str(cwd_root)):
+                        logger.warning("Skipping file outside cwd: %s -> %s", entry.path, resolved)
+                        continue
+                    try:
+                        size = resolved.stat().st_size
+                    except OSError:
+                        continue
+                    if size > MAX_GENERATED_FILE_BYTES:
+                        logger.warning("Skipping oversized file: %s (%d bytes)", entry.path, size)
+                        continue
+                    out[str(resolved)] = entry.stat().st_mtime
+        except OSError:
+            pass
+
+    def _detect_new_files(
+        self, before: dict[str, float], cwd: str | None
+    ) -> list[str]:
+        """Return paths of image files created or modified since the snapshot."""
+        if not cwd:
+            return []
+        after = self._snapshot_image_files(cwd)
+        new_files = []
+        for path, mtime in after.items():
+            if path not in before or mtime > before[path]:
+                new_files.append(path)
+        return sorted(new_files)
+
+    async def invoke(
+        self,
+        prompt: str,
+        session_id: str | None = None,
+        timeout: int = 300,
+        cwd: str | None = None,
+    ) -> LocalInvocationResult:
+        """Run the CLI subprocess, parse output.
+
+        Raises :class:`TimeoutError` on timeout, :class:`RuntimeError` on
+        non-zero exit, and :class:`~agenthive.rate_limit.RateLimitError` when
+        rate-limit patterns are detected.
+        """
+        cmd = self._build_args(session_id)
+        stdin_data = self._get_stdin_data(prompt)
+
+        logger.info("Invoking %s: %s", self.__class__.__name__, " ".join(cmd))
+        logger.debug("stdin (%d chars): %s", len(prompt), prompt[:200])
+
+        # Snapshot image files before invocation to detect new ones
+        before_files = self._snapshot_image_files(cwd)
+
+        t0 = time.monotonic()
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE if stdin_data else None,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+        )
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(stdin_data.encode() if stdin_data else None),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            logger.error("Subprocess timed out after %ds", timeout)
+            raise TimeoutError(f"Subprocess timed out after {timeout}s")
+
+        duration = time.monotonic() - t0
+        stdout_text = stdout_bytes.decode(errors="replace")
+        stderr_text = stderr_bytes.decode(errors="replace")
+
+        if proc.returncode != 0:
+            logger.error(
+                "Subprocess failed (exit %d) in %.1fs: %s",
+                proc.returncode,
+                duration,
+                stderr_text[:300],
+            )
+            # Check for rate-limit signals
+            from agentshive.rate_limit import classify_rate_limit, RateLimitError
+
+            combined = f"{stdout_text}\n{stderr_text}"
+            snippet = classify_rate_limit(combined)
+            if snippet:
+                logger.warning("Rate limit detected: %s", snippet[:100])
+                raise RateLimitError("local_backend", snippet)
+            raise RuntimeError(f"Subprocess exited with code {proc.returncode}")
+
+        logger.info(
+            "Subprocess completed in %.1fs (exit=%d, stdout=%d chars)",
+            duration, proc.returncode, len(stdout_text),
+        )
+        logger.debug("stdout: %s", stdout_text[:500])
+        if stderr_text:
+            logger.debug("stderr: %s", stderr_text[:500])
+
+        result = self._parse_output(stdout_text)
+
+        # Detect image files created during invocation
+        new_files = self._detect_new_files(before_files, cwd)
+        if new_files:
+            result.generated_files = new_files
+            logger.info("Detected %d generated image files: %s", len(new_files), new_files)
+
+        logger.info(
+            "Parsed: text=%d chars, session_id=%s, tokens=%d/%d",
+            len(result.text),
+            result.session_id[:8] if result.session_id else None,
+            result.input_tokens,
+            result.output_tokens,
+        )
+        return result

agentshive/backends/claude_code.py

@@ -0,0 +1,57 @@
+"""Claude Code CLI backend."""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+
+from .base import LocalCliBackend, LocalInvocationResult
+
+logger = logging.getLogger(__name__)
+
+
+class LocalClaudeCodeBackend(LocalCliBackend):
+    """Wraps the ``claude`` CLI (Claude Code)."""
+
+    supports_resume = True
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return shutil.which("claude") is not None
+
+    def _base_command(self) -> list[str]:
+        return [
+            "claude",
+            "--print",
+            "--dangerously-skip-permissions",
+            "--output-format",
+            "json",
+            "-p",
+        ]
+
+    def _build_args(self, session_id: str | None = None) -> list[str]:
+        args = list(self._base_command())
+        if session_id:
+            p_idx = args.index("-p")
+            args.insert(p_idx, "--resume")
+            args.insert(p_idx + 1, session_id)
+        return args
+
+    def _parse_output(self, stdout: str) -> LocalInvocationResult:
+        try:
+            data = json.loads(stdout)
+        except json.JSONDecodeError:
+            logger.warning("Failed to parse JSON from claude output, treating as plain text")
+            return LocalInvocationResult(text=stdout.strip())
+
+        usage = data.get("usage", {})
+        return LocalInvocationResult(
+            text=data.get("result", ""),
+            session_id=data.get("session_id"),
+            stop_reason=data.get("stop_reason") or data.get("stopReason"),
+            input_tokens=usage.get("input_tokens", 0),
+            output_tokens=usage.get("output_tokens", 0),
+            cache_read_tokens=usage.get("cache_read_input_tokens", 0),
+            cost_usd=data.get("total_cost_usd", 0.0),
+        )