moonbridge 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

moonbridge/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 from .server import main, run, server
 

moonbridge/server.py

@@ -21,6 +21,7 @@ from mcp.types import TextContent, Tool
 
 from moonbridge.adapters import ADAPTER_REGISTRY, CLIAdapter, get_adapter
 from moonbridge.adapters.base import AgentResult
+from moonbridge.signals import extract_quality_signals
 from moonbridge.tools import build_tools
 
 server = Server("moonbridge")
@@ -78,6 +79,22 @@ def _warn_if_unrestricted() -> None:
     print(message, file=sys.stderr)
 
 
+def _validate_allowed_dirs() -> None:
+    if not ALLOWED_DIRS:
+        return
+    missing_count = 0
+    for path in ALLOWED_DIRS:
+        if os.path.isdir(path):
+            continue
+        missing_count += 1
+        logger.warning("MOONBRIDGE_ALLOWED_DIRS entry does not exist: %s", path)
+    if missing_count == len(ALLOWED_DIRS) and STRICT_MODE:
+        message = "MOONBRIDGE_ALLOWED_DIRS entries do not exist"
+        logger.error(message)
+        print(message, file=sys.stderr)
+        sys.exit(1)
+
+
 def _safe_env(adapter: CLIAdapter) -> dict[str, str]:
     env = {key: os.environ[key] for key in adapter.config.safe_env_keys if key in os.environ}
     if "PATH" not in env and "PATH" in os.environ:
@@ -327,7 +344,7 @@ def _run_cli_sync(
             )
         status = "success" if proc.returncode == 0 else "error"
         logger.info("Agent %s completed with status: %s", agent_index, status)
-        return AgentResult(
+        result = AgentResult(
             status=status,
             output=stdout,
             stderr=stderr_value,
@@ -335,6 +352,13 @@ def _run_cli_sync(
             duration_ms=duration_ms,
             agent_index=agent_index,
         )
+        if result.status == "success":
+            signals = extract_quality_signals(result.output, result.stderr)
+            if signals:
+                raw = dict(result.raw or {})
+                raw["quality_signals"] = signals
+                result = replace(result, raw=raw)
+        return result
     except TimeoutExpired:
         _terminate_process(proc)
         duration_ms = int((time.monotonic() - start) * 1000)
@@ -401,6 +425,12 @@ def _json_text(payload: Any) -> list[TextContent]:
 
 
 def _status_check(cwd: str, adapter: CLIAdapter) -> dict[str, Any]:
+    config = {
+        "strict_mode": STRICT_MODE,
+        "allowed_dirs": ALLOWED_DIRS or None,
+        "unrestricted": not ALLOWED_DIRS,
+        "cwd": cwd,
+    }
     installed, _path = adapter.check_installed()
     if not installed:
         return {
@@ -408,20 +438,27 @@ def _status_check(cwd: str, adapter: CLIAdapter) -> dict[str, Any]:
             "message": (
                 f"{adapter.config.name} CLI not found. Install: {adapter.config.install_hint}"
             ),
+            "config": config,
         }
     timeout = min(DEFAULT_TIMEOUT, 60)
     result = _run_cli_sync(adapter, "status check", False, cwd, timeout, 0)
     if result.status == "auth_error":
-        return {"status": "auth_error", "message": adapter.config.auth_message}
+        return {
+            "status": "auth_error",
+            "message": adapter.config.auth_message,
+            "config": config,
+        }
     if result.status == "success":
         return {
             "status": "success",
             "message": f"{adapter.config.name} CLI available and authenticated",
+            "config": config,
         }
     return {
         "status": "error",
         "message": f"{adapter.config.name} CLI error",
         "details": result.to_dict(),
+        "config": config,
     }
 
 
@@ -444,6 +481,7 @@ def _adapter_info(cwd: str, adapter: CLIAdapter) -> dict[str, Any]:
 
 @server.list_tools()
 async def list_tools() -> list[Tool]:
+    """Build MCP tool metadata for the active adapter."""
     adapter = get_adapter()
     tool_desc = adapter.config.tool_description
     status_desc = f"Verify {adapter.config.name} CLI is installed and authenticated"
@@ -456,7 +494,15 @@ async def list_tools() -> list[Tool]:
 
 
 async def handle_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
-    """Handle tool calls. Exposed for testing."""
+    """Dispatch a tool invocation with validation and stable error payloads.
+
+    Separated from ``call_tool`` so tests can invoke tool logic without the
+    MCP decorator.
+
+    Args:
+        name: MCP tool name (``spawn_agent``, ``spawn_agents_parallel``, etc.).
+        arguments: Tool argument payload from the MCP client.
+    """
     try:
         cwd = _validate_cwd(None)
         if name == "spawn_agent":
@@ -556,11 +602,12 @@ async def handle_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]
 
 @server.call_tool()
 async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
-    """MCP tool handler - delegates to handle_tool."""
+    """MCP tool handler -- delegates to ``handle_tool`` for testability."""
     return await handle_tool(name, arguments)
 
 
 async def run() -> None:
+    """Run the MCP server over stdio until the client disconnects."""
     async with stdio_server() as (read_stream, write_stream):
         await server.run(
             read_stream,
@@ -570,8 +617,10 @@ async def run() -> None:
 
 
 def main() -> None:
+    """CLI entry point that validates prerequisites then starts the server."""
     _configure_logging()
     _warn_if_unrestricted()
+    _validate_allowed_dirs()
     from moonbridge import __version__
     from moonbridge.version_check import check_for_updates
 

moonbridge/signals.py

@@ -0,0 +1,68 @@
+"""Heuristic extraction of quality signals from agent output."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# Diff markers at line start.
+_DIFF_MARKER_RE = re.compile(r"^(?:\+\+\+ |--- |@@ )", re.MULTILINE)
+# File headers in unified diffs.
+_DIFF_FILE_RE = re.compile(r"^(?:\+\+\+ b/|--- a/)(.+)$", re.MULTILINE)
+# Git-style summary lines.
+_FILES_CHANGED_RE = re.compile(r"\b(\d+)\s+files?\s+changed\b", re.IGNORECASE)
+_MODIFIED_FILES_RE = re.compile(r"\bModified\s+(\d+)\s+files?\b", re.IGNORECASE)
+# Pytest-style summaries.
+_PASSED_RE = re.compile(r"(?<!\w)(\d+)\s+passed\b", re.IGNORECASE)
+_FAILED_RE = re.compile(r"(?<!\w)(\d+)\s+failed\b", re.IGNORECASE)
+# stderr error markers.
+_ERROR_RE = re.compile(r"(Traceback \(most recent call last\)|\berror:)", re.IGNORECASE)
+
+
+def _last_int(pattern: re.Pattern[str], text: str) -> int | None:
+    matches = pattern.findall(text)
+    if not matches:
+        return None
+    return int(matches[-1])
+
+
+def _count_files_changed(output: str) -> int:
+    paths = {path for path in _DIFF_FILE_RE.findall(output) if path and path != "/dev/null"}
+    if paths:
+        return len(paths)
+    match = _FILES_CHANGED_RE.search(output) or _MODIFIED_FILES_RE.search(output)
+    if match:
+        return int(match.group(1))
+    return 0
+
+
+def extract_quality_signals(output: str, stderr: str | None = None) -> dict[str, Any]:
+    """Extract heuristic quality signals from agent output."""
+    signals: dict[str, Any] = {}
+    if not output and not stderr:
+        return signals
+
+    has_diff = bool(_DIFF_MARKER_RE.search(output))
+    if has_diff:
+        signals["has_diff"] = True
+
+    files_changed = _count_files_changed(output)
+    if files_changed:
+        signals["files_changed"] = files_changed
+
+    combined = output
+    if stderr:
+        combined = f"{output}\n{stderr}"
+
+    tests_passed = _last_int(_PASSED_RE, combined)
+    if tests_passed is not None:
+        signals["tests_passed"] = tests_passed
+
+    tests_failed = _last_int(_FAILED_RE, combined)
+    if tests_failed is not None:
+        signals["tests_failed"] = tests_failed
+
+    if stderr and _ERROR_RE.search(stderr):
+        signals["has_errors"] = True
+
+    return signals

{moonbridge-0.8.0.dist-info → moonbridge-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moonbridge
-Version: 0.8.0
+Version: 0.9.0
 Summary: MCP server for spawning AI coding agents (Kimi, Codex, and more)
 Project-URL: Homepage, https://github.com/misty-step/moonbridge
 Project-URL: Repository, https://github.com/misty-step/moonbridge
@@ -90,6 +90,32 @@ export MOONBRIDGE_SKIP_UPDATE_CHECK=1
 
 **Best for:** Tasks that benefit from parallel execution or volume.
 
+## How it Works
+
+### Connection Flow
+1. MCP client (Claude Code, Cursor, etc.) connects to Moonbridge over stdio
+2. Client discovers available tools via `list_tools`
+3. Client calls `spawn_agent` or `spawn_agents_parallel`
+
+### Spawn Process
+1. Moonbridge validates the prompt and working directory
+2. Resolves which adapter to use (Kimi, Codex)
+3. Adapter builds the CLI command with appropriate flags
+4. Spawns subprocess in a separate process group
+5. Captures stdout/stderr, enforces timeout
+6. Returns structured JSON result
+
+### Parallel Execution
+- `spawn_agents_parallel` runs up to 10 agents concurrently via `asyncio.gather`
+- Each agent is independent (separate process, separate output)
+- All results returned together when the last agent finishes (or times out)
+
+```
+MCP Client → stdio → Moonbridge → adapter → CLI subprocess
+                                          → CLI subprocess (parallel)
+                                          → CLI subprocess (parallel)
+```
+
 ## Tools
 
 | Tool | Use case |
@@ -170,6 +196,31 @@ All tools return JSON with these fields:
 | `MOONBRIDGE_SANDBOX_MAX_COPY` | Max sandbox copy size in bytes (default 500MB) |
 | `MOONBRIDGE_LOG_LEVEL` | Set to `DEBUG` for verbose logging |
 
+## Security
+
+### 1. Directory Restrictions (`MOONBRIDGE_ALLOWED_DIRS`)
+
+Default: agents can operate in any directory. Set `MOONBRIDGE_ALLOWED_DIRS` to restrict: colon-separated allowed paths. Symlinks resolved via `os.path.realpath` before checking. Strict mode (`MOONBRIDGE_STRICT=1`) exits on startup if no valid allowed directories are configured.
+
+```bash
+export MOONBRIDGE_ALLOWED_DIRS="/home/user/projects:/home/user/work"
+export MOONBRIDGE_STRICT=1  # require restrictions
+```
+
+### 2. Environment Sanitization
+
+Only whitelisted env vars are passed to spawned agents. Each adapter defines its own allowlist (`PATH`, `HOME`, plus adapter-specific like `OPENAI_API_KEY` for Codex). Your shell environment (secrets, tokens, SSH keys) is not inherited by default.
+
+### 3. Input Validation
+
+Model parameters are validated to prevent flag injection (values starting with `-` are rejected). Prompts are capped at 100,000 characters and cannot be empty.
+
+### 4. Process Isolation
+
+Agents run in separate process groups (`start_new_session=True`). Orphan cleanup on exit. Sandbox mode available (`MOONBRIDGE_SANDBOX=1`) for copy-on-run isolation.
+
+> **Not OS-level sandboxing.** Agents can still read arbitrary host files. For strong isolation, use containers/VMs.
+
 ## Troubleshooting
 
 ### "CLI not found"

{moonbridge-0.8.0.dist-info → moonbridge-0.9.0.dist-info}/RECORD

@@ -1,15 +1,16 @@
-moonbridge/__init__.py,sha256=8Yz-_YwybWMK-Sze7iG20GXQGLCNhL7dBjHmblAHULA,198
+moonbridge/__init__.py,sha256=ARkdZ2AN2BQF7Jf4ECee-WXhmAGnSDwkJoftXCqure4,198
 moonbridge/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 moonbridge/sandbox.py,sha256=4-eIu-rURtaxKKg-d3iWwNq_x6MB_uiJBBG2uMwoKcM,7907
-moonbridge/server.py,sha256=FqnoAd-WAWOX-elNgyOQ-vAiFqsGOdsyQCIsnu1e1t0,19469
+moonbridge/server.py,sha256=bRvDSvxpmbRWeMKA1JAczmqL2PcpsWfZtjM1jGQL0OE,21195
+moonbridge/signals.py,sha256=tpdKuVBIrQ9XOZm6WaxcNSSPj9WqWUYp6aGseGq9W6I,2210
 moonbridge/tools.py,sha256=uw338Dilrto2t5dL9XbK4O31-JdB7Vh9RqCXHg20gHI,10126
 moonbridge/version_check.py,sha256=VQueK0O_b-2Xc-XjupJsoW3Zs1Kce5q_BgqBhANGXN8,4579
 moonbridge/adapters/__init__.py,sha256=w3pLvjtC2XnUhf9UzNmniQB3oq4rG8gorSH0tWR-BEE,988
 moonbridge/adapters/base.py,sha256=REoEsAcqEvyVQpTgz6ytd9ioxag--nnvX90YBXMQG8Y,1716
 moonbridge/adapters/codex.py,sha256=G0q_A6vP5Usqix3sE8ssrG_qzrCWMeFcO9oWcNKTO3g,2964
 moonbridge/adapters/kimi.py,sha256=ejCxG2OGr0Qr4n0psL6p96_mMJ3lLKMbGcNYWkuC0uA,2189
-moonbridge-0.8.0.dist-info/METADATA,sha256=RiRWB1Hr5IFT3wEpRHVcqIclyBS2CORWE-j90Z4C19U,8305
-moonbridge-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-moonbridge-0.8.0.dist-info/entry_points.txt,sha256=kgL38HQy3adncDQl_o5sdtPRog56zKdHk6pKKzyR6Ww,54
-moonbridge-0.8.0.dist-info/licenses/LICENSE,sha256=7WMSJoybL2cUot_wb9GUrw5mzfFmtrDzqlMS9ZE709g,1065
-moonbridge-0.8.0.dist-info/RECORD,,
+moonbridge-0.9.0.dist-info/METADATA,sha256=T_721mqFlkFCMcUvgimOVMT79fJ12bqpe1XDTxVmbIo,10564
+moonbridge-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+moonbridge-0.9.0.dist-info/entry_points.txt,sha256=kgL38HQy3adncDQl_o5sdtPRog56zKdHk6pKKzyR6Ww,54
+moonbridge-0.9.0.dist-info/licenses/LICENSE,sha256=7WMSJoybL2cUot_wb9GUrw5mzfFmtrDzqlMS9ZE709g,1065
+moonbridge-0.9.0.dist-info/RECORD,,