gobby 0.2.5__py3-none-any.whl

gobby/utils/daemon_client.py

@@ -0,0 +1,235 @@
+"""
+DaemonClient - HTTP communication with Gobby daemon.
+
+This module provides a clean interface for communicating with the Gobby daemon's
+HTTP API. It handles health checks, authentication verification, and HTTP API calls.
+
+The DaemonClient is session-agnostic and thread-safe, designed to be shared across
+multiple sessions while maintaining cached health status for performance.
+
+Example:
+    ```python
+    from gobby.utils.daemon_client import DaemonClient
+
+    client = DaemonClient(host="localhost", port=8765)
+
+    # Check daemon health
+    is_healthy, error = client.check_health()
+
+    # Call HTTP API endpoint
+    response = client.call_http_api("/sessions/register", method="POST", json_data={
+        "external_id": "abc123"
+    })
+    ```
+"""
+
+import logging
+import threading
+from typing import Any, ClassVar, cast
+
+import httpx
+
+
+class DaemonClient:
+    """
+    Client for communicating with Gobby daemon HTTP API.
+
+    Provides methods for:
+    - Health checking with caching
+    - Authentication verification
+    - HTTP API calls
+
+    Thread-safe and session-agnostic.
+
+    Attributes:
+        url: Base URL for daemon HTTP API
+        timeout: Request timeout in seconds
+        logger: Logger instance for this client
+    """
+
+    # Status text mapping (class-level constant)
+    DAEMON_STATUS_TEXT: ClassVar[dict[str, str]] = {
+        "not_running": "Not Running",
+        "cannot_access": "Cannot Access",
+        "ready": "Ready",
+    }
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 8765,
+        timeout: float = 5.0,
+        logger: logging.Logger | None = None,
+    ):
+        """
+        Initialize DaemonClient.
+
+        Args:
+            host: Daemon host address
+            port: Daemon port number
+            timeout: HTTP request timeout in seconds
+            logger: Optional logger instance (creates one if not provided)
+        """
+        self.url = f"http://{host}:{port}"
+        self.timeout = timeout
+        self.logger = logger or logging.getLogger(__name__)
+
+        # Health status cache (thread-safe)
+        self._cache_lock = threading.Lock()
+        self._cached_is_ready: bool | None = None
+        self._cached_message: str | None = None
+        self._cached_status: str | None = None
+        self._cached_error: str | None = None
+
+    def check_health(self) -> tuple[bool, str | None]:
+        """
+        Check if daemon is available and healthy.
+
+        Returns:
+            Tuple of (is_healthy, error_reason) where:
+            - is_healthy: True if daemon is healthy, False otherwise
+            - error_reason: None if healthy, otherwise error description
+        """
+        try:
+            response = httpx.get(
+                f"{self.url}/admin/status",
+                timeout=self.timeout,
+            )
+            is_healthy = response.status_code == 200
+            if is_healthy:
+                self.logger.info(f"Daemon health check passed at {self.url}")
+                return True, None
+            else:
+                error_reason = f"HTTP {response.status_code}"
+                self.logger.warning(f"Daemon health check failed: status {response.status_code}")
+                return False, error_reason
+        except Exception as e:
+            error_msg = str(e)
+            # Check if it's a connection refused (daemon not running)
+            if "refused" in error_msg.lower() or "connection" in error_msg.lower():
+                self.logger.warning(f"Daemon not running: {e}")
+                return False, None  # None means daemon not running
+            else:
+                # Other errors (timeout, DNS, etc.)
+                self.logger.error(f"Daemon health check error: {e}")
+                return False, error_msg
+
+    def check_status(self) -> tuple[bool, str | None, str, str | None]:
+        """
+        Check daemon health status.
+
+        Returns:
+            Tuple of (is_ready, message, status, error_reason) where:
+            - is_ready: True if daemon is healthy
+            - message: Human-readable status message
+            - status: One of: "ready", "not_running", "cannot_access"
+            - error_reason: Error details if status != "ready"
+        """
+        is_healthy, health_error = self.check_health()
+
+        if not is_healthy:
+            if health_error is None:
+                return False, "Daemon is not running", "not_running", None
+            else:
+                return False, f"Cannot access daemon: {health_error}", "cannot_access", health_error
+
+        return True, "Daemon is ready", "ready", None
+
+    def call_http_api(
+        self,
+        endpoint: str,
+        method: str = "POST",
+        json_data: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """
+        Call daemon HTTP API endpoint directly (for non-MCP endpoints).
+
+        Args:
+            endpoint: API endpoint path (e.g., "/sessions/register")
+            method: HTTP method (default: POST)
+            json_data: JSON data to send
+            timeout: Request timeout (default: uses self.timeout)
+
+        Returns:
+            Response object (httpx.Response)
+        """
+        url = f"{self.url}{endpoint}"
+        timeout_val = timeout or self.timeout
+
+        try:
+            if method.upper() == "GET":
+                response = httpx.get(url, timeout=timeout_val)
+            elif method.upper() == "POST":
+                response = httpx.post(url, json=json_data, timeout=timeout_val)
+            elif method.upper() == "PUT":
+                response = httpx.put(url, json=json_data, timeout=timeout_val)
+            elif method.upper() == "DELETE":
+                response = httpx.delete(url, timeout=timeout_val)
+            else:
+                raise ValueError(f"Unsupported HTTP method: {method}")
+
+            return response
+
+        except Exception as e:
+            self.logger.error(f"HTTP API call failed: {method} {endpoint} - {e}")
+            raise
+
+    def call_mcp_tool(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict[str, Any],
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """
+        Call an MCP tool via the daemon's HTTP API.
+
+        Args:
+            server_name: Name of the MCP server
+            tool_name: Name of the tool to call
+            arguments: Tool arguments
+            timeout: Request timeout
+
+        Returns:
+            Tool execution result
+        """
+        endpoint = f"/mcp/{server_name}/tools/{tool_name}"
+        response = self.call_http_api(
+            endpoint=endpoint,
+            method="POST",
+            json_data=arguments,
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return cast(dict[str, Any], response.json())
+
+    def update_status_cache(self) -> None:
+        """Update cached daemon status by calling check_status()."""
+        with self._cache_lock:
+            (
+                self._cached_is_ready,
+                self._cached_message,
+                self._cached_status,
+                self._cached_error,
+            ) = self.check_status()
+
+            self.logger.debug(
+                f"Daemon status updated: {self.DAEMON_STATUS_TEXT.get(self._cached_status, 'Unknown')}"
+            )
+
+    def get_cached_status(self) -> tuple[bool | None, str | None, str | None, str | None]:
+        """
+        Get cached daemon status without making HTTP calls.
+
+        Returns:
+            Tuple of (is_ready, message, status, error_reason)
+            Values may be None if status hasn't been checked yet.
+        """
+        with self._cache_lock:
+            return (
+                self._cached_is_ready,
+                self._cached_message,
+                self._cached_status,
+                self._cached_error,
+            )

gobby/utils/git.py

@@ -0,0 +1,222 @@
+"""
+Git metadata extraction utilities for Gobby Client.
+
+Provides functions to extract git repository information including:
+- Repository remote URL
+- Current branch name
+
+Handles git worktrees, detached HEAD, and missing remotes gracefully.
+"""
+
+import logging
+import subprocess  # nosec B404 - subprocess needed for git commands
+from pathlib import Path
+from typing import TypedDict
+
+logger = logging.getLogger(__name__)
+
+
+class GitMetadata(TypedDict, total=False):
+    """Git repository metadata structure."""
+
+    github_url: str | None
+    git_branch: str | None
+
+
+def run_git_command(command: list[str], cwd: str | Path, timeout: int = 5) -> str | None:
+    """
+    Execute a git command safely with timeout protection.
+
+    Args:
+        command: Git command as list of strings (e.g., ["git", "branch", "--show-current"])
+        cwd: Working directory where git command should run
+        timeout: Command timeout in seconds (default: 5)
+
+    Returns:
+        Command output as string (stripped), or None if command fails
+    """
+    try:
+        result = subprocess.run(  # nosec B603 - command passed from internal callers with hardcoded git commands
+            command,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,  # Don't raise on non-zero exit
+        )
+
+        if result.returncode == 0:
+            return result.stdout.strip()
+
+        logger.debug(f"Git command failed: {' '.join(command)}, stderr: {result.stderr.strip()}")
+        return None
+
+    except subprocess.TimeoutExpired:
+        logger.warning(f"Git command timed out after {timeout}s: {' '.join(command)}")
+        return None
+    except FileNotFoundError:
+        logger.warning("Git executable not found in PATH")
+        return None
+    except Exception as e:
+        logger.error(f"Git command error: {' '.join(command)}, error: {e}")
+        return None
+
+
+def get_github_url(cwd: str | Path) -> str | None:
+    """
+    Extract git repository URL from origin remote.
+
+    Args:
+        cwd: Working directory (git repository path)
+
+    Returns:
+        Remote URL string, or None if not available
+    """
+    # Try to get origin remote URL
+    url = run_git_command(["git", "remote", "get-url", "origin"], cwd)
+
+    if url:
+        # Sanitize URL (remove auth tokens, convert SSH to HTTPS for privacy)
+        # Keep original format for now - can sanitize later if needed
+        return url
+
+    # If origin doesn't exist, try to list all remotes and use first one
+    remotes = run_git_command(["git", "remote"], cwd)
+    if remotes:
+        remote_names = remotes.split("\n")
+        if remote_names:
+            first_remote = remote_names[0]
+            url = run_git_command(["git", "remote", "get-url", first_remote], cwd)
+            if url:
+                logger.debug(f"Using remote '{first_remote}' (origin not found)")
+                return url
+
+    logger.debug("No git remotes found")
+    return None
+
+
+def get_git_branch(cwd: str | Path) -> str | None:
+    """
+    Get current git branch name.
+
+    Handles detached HEAD state gracefully.
+
+    Args:
+        cwd: Working directory (git repository path)
+
+    Returns:
+        Branch name string, or None if detached HEAD or error
+    """
+    branch = run_git_command(["git", "branch", "--show-current"], cwd)
+
+    if branch:
+        return branch
+
+    # Check if we're in detached HEAD state
+    symbolic_ref = run_git_command(["git", "symbolic-ref", "-q", "HEAD"], cwd)
+    if symbolic_ref is None:
+        logger.debug("Git repository in detached HEAD state")
+        return None  # Detached HEAD
+
+    logger.debug("Unable to determine current git branch")
+    return None
+
+
+def get_git_metadata(cwd: str | Path | None = None) -> GitMetadata:
+    """
+    Extract comprehensive git repository metadata.
+
+    Extracts:
+    - github_url: Remote repository URL (from origin or first remote)
+    - git_branch: Current branch name (None if detached HEAD)
+
+    Handles errors gracefully and works with git worktrees.
+
+    Args:
+        cwd: Working directory to check. Defaults to current directory.
+
+    Returns:
+        GitMetadata dict with available information.
+        All fields are optional and will be None if unavailable.
+
+    Example:
+        >>> metadata = get_git_metadata("/path/to/repo")
+        >>> metadata["github_url"]
+        'https://github.com/user/repo.git'
+        >>> metadata["git_branch"]
+        'main'
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+    else:
+        cwd = Path(cwd)
+
+    # Verify path exists
+    if not cwd.exists():
+        logger.warning(f"Path does not exist: {cwd}")
+        return GitMetadata()
+
+    # Check if directory is in a git repository
+    is_git_repo = run_git_command(["git", "rev-parse", "--git-dir"], cwd)
+    if not is_git_repo:
+        logger.debug(f"Not a git repository: {cwd}")
+        return GitMetadata()
+
+    # Extract metadata
+    metadata = GitMetadata()
+
+    try:
+        metadata["github_url"] = get_github_url(cwd)
+        metadata["git_branch"] = get_git_branch(cwd)
+
+        logger.debug(
+            f"Git metadata extracted: repo={metadata.get('github_url')}, "
+            f"branch={metadata.get('git_branch')}"
+        )
+
+    except Exception as e:
+        logger.error(f"Error extracting git metadata: {e}")
+
+    return metadata
+
+
+def normalize_commit_sha(sha: str, cwd: str | Path | None = None) -> str | None:
+    """
+    Normalize a commit SHA to dynamic short format.
+
+    Uses git rev-parse --short which returns the minimum characters
+    needed for uniqueness (typically 7, more in large repos).
+
+    Args:
+        sha: Short or full commit SHA
+        cwd: Working directory for git commands (defaults to current directory)
+
+    Returns:
+        Shortened SHA (7+ chars), or None if SHA cannot be resolved
+    """
+    if not sha or len(sha) < 4:
+        return None
+
+    if cwd is None:
+        cwd = Path.cwd()
+
+    # Use git rev-parse --short to get canonical short form
+    result = run_git_command(["git", "rev-parse", "--short", sha], cwd=cwd)
+    return result if result else None
+
+
+def is_valid_sha_format(sha: str) -> bool:
+    """
+    Check if string looks like a valid SHA format (hex, >= 4 chars).
+
+    This is a format check only - does not verify the SHA exists in any repo.
+
+    Args:
+        sha: String to validate
+
+    Returns:
+        True if string could be a valid SHA format
+    """
+    if not sha or len(sha) < 4:
+        return False
+    return all(c in "0123456789abcdefABCDEF" for c in sha)

gobby/utils/id.py

@@ -0,0 +1,38 @@
+"""ID generation utilities."""
+
+import hashlib
+import uuid
+
+
+def generate_prefixed_id(prefix: str, content: str | None = None, length: int = 8) -> str:
+    """
+    Generate a prefixed ID (e.g., 'mm-a1b2c3d4').
+
+    If content is provided, the ID is deterministic based on the content hash.
+    If content is None, a random UUID is used.
+
+    Args:
+        prefix: The prefix for the ID (e.g., 'mm', 'sk')
+        content: Optional content to hash for deterministic IDs
+        length: Length of the hash part (default: 8)
+
+    Returns:
+        Formatted ID string
+        Raises:
+        ValueError: If prefix is empty or length is invalid
+    """
+    if not prefix:
+        raise ValueError("prefix cannot be empty")
+    if length <= 0:
+        raise ValueError("length must be positive")
+    if length > 64:  # SHA-256 produces 64 hex characters
+        raise ValueError("length cannot exceed 64")
+
+    if content is not None:
+        hash_obj = hashlib.sha256(content.encode("utf-8"))
+        hash_hex = hash_obj.hexdigest()[:length]
+    else:
+        # Use random UUID if no content provided
+        hash_hex = uuid.uuid4().hex[:length]
+
+    return f"{prefix}-{hash_hex}"

gobby/utils/json_helpers.py

@@ -0,0 +1,161 @@
+"""JSON extraction utilities for parsing LLM responses.
+
+This module provides robust JSON extraction from text that may contain
+markdown code blocks, preamble text, or other non-JSON content.
+
+Also provides typed JSON decoding using msgspec for structured LLM responses.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import msgspec
+
+logger = logging.getLogger(__name__)
+
+
+def extract_json_from_text(text: str) -> str | None:
+    """
+    Extract JSON from text, handling markdown code blocks and mixed content.
+
+    Uses json.JSONDecoder.raw_decode() which properly handles all JSON
+    edge cases (nested strings, escapes, backticks in strings, etc.)
+    rather than brittle regex patterns.
+
+    Args:
+        text: Raw text that may contain JSON, possibly wrapped in markdown
+              code blocks or with preamble/postamble text.
+
+    Returns:
+        Extracted JSON string, or None if no valid JSON found.
+
+    Examples:
+        >>> extract_json_from_text('{"key": "value"}')
+        '{"key": "value"}'
+
+        >>> extract_json_from_text('Here is the result:\\n```json\\n{"key": "value"}\\n```')
+        '{"key": "value"}'
+
+        >>> extract_json_from_text('No JSON here')
+        None
+    """
+    if not text:
+        return None
+
+    decoder = json.JSONDecoder()
+
+    # Build list of positions to try, prioritizing code block content
+    positions_to_try: list[int] = []
+
+    # Look for ```json marker first (most specific)
+    code_block_idx = text.find("```json")
+    if code_block_idx != -1:
+        brace_pos = text.find("{", code_block_idx + 7)
+        if brace_pos != -1:
+            positions_to_try.append(brace_pos)
+
+    # Then try plain ``` marker
+    if not positions_to_try:
+        code_block_idx = text.find("```")
+        if code_block_idx != -1:
+            brace_pos = text.find("{", code_block_idx + 3)
+            if brace_pos != -1:
+                positions_to_try.append(brace_pos)
+
+    # Finally try raw JSON (first { in text)
+    first_brace = text.find("{")
+    if first_brace != -1 and first_brace not in positions_to_try:
+        positions_to_try.append(first_brace)
+
+    # Try each position until we find valid JSON
+    for pos in positions_to_try:
+        try:
+            # raw_decode returns (obj, end_idx) where end_idx is absolute position
+            _, end_idx = decoder.raw_decode(text, pos)
+            return text[pos:end_idx]
+        except json.JSONDecodeError:
+            continue
+
+    return None
+
+
+def extract_json_object(text: str) -> dict[str, Any] | None:
+    """
+    Extract and parse a JSON object from text.
+
+    Convenience wrapper that extracts JSON string and parses it.
+
+    Args:
+        text: Raw text that may contain JSON.
+
+    Returns:
+        Parsed JSON dict, or None if no valid JSON found.
+    """
+    json_str = extract_json_from_text(text)
+    if json_str is None:
+        return None
+
+    try:
+        result = json.loads(json_str)
+        if isinstance(result, dict):
+            return result
+        logger.warning(f"Extracted JSON is not an object: {type(result)}")
+        return None
+    except json.JSONDecodeError as e:
+        logger.warning(f"Failed to parse extracted JSON: {e}")
+        return None
+
+
+def decode_llm_response[T](
+    text: str,
+    response_type: type[T],
+    *,
+    strict: bool = True,
+) -> T | None:
+    """
+    Extract JSON from LLM response and decode to a typed struct.
+
+    Uses msgspec for efficient, type-safe JSON decoding with clear error messages.
+    Combines extract_json_from_text() with msgspec.json.decode().
+
+    Args:
+        text: Raw LLM response text (may contain markdown code blocks, preamble, etc.)
+        response_type: The msgspec.Struct or other type to decode to
+        strict: If True (default), type mismatches raise errors.
+                If False, allows coercion (e.g., "5" -> 5 for int fields).
+                Configure via llm_providers.json_strict in config.yaml,
+                or override per-workflow with llm_json_strict variable.
+
+    Returns:
+        Decoded response of type T, or None if extraction/decoding fails.
+
+    Examples:
+        >>> class TaskResult(msgspec.Struct):
+        ...     status: str
+        ...     count: int
+        >>> result = decode_llm_response('{"status": "ok", "count": 5}', TaskResult)
+        >>> result.status
+        'ok'
+
+        >>> # With strict=False, string "5" coerces to int 5
+        >>> result = decode_llm_response('{"status": "ok", "count": "5"}', TaskResult, strict=False)
+        >>> result.count
+        5
+    """
+    json_str = extract_json_from_text(text)
+    if json_str is None:
+        logger.debug("No JSON found in LLM response")
+        return None
+
+    try:
+        # msgspec.json.decode returns Any at runtime when using TypeVar
+        return msgspec.json.decode(json_str.encode(), type=response_type, strict=strict)
+    except msgspec.ValidationError as e:
+        logger.warning(f"Invalid LLM response structure: {e}")
+        return None
+    except msgspec.DecodeError as e:
+        logger.warning(f"Failed to decode LLM response JSON: {e}")
+        return None