meshcode 2.11.93__tar.gz → 2.11.94__tar.gz

{meshcode-2.11.93 → meshcode-2.11.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.93
+Version: 2.11.94
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT

{meshcode-2.11.93 → meshcode-2.11.94}/meshcode/__init__.py

@@ -1,5 +1,5 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.11.93"
+__version__ = "2.11.94"
 
 # Exception hierarchy — eagerly imported (lightweight, no deps)
 from meshcode.exceptions import (  # noqa: F401

meshcode-2.11.94/meshcode/cli.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""MeshCode CLI entry point for pip install."""
+import sys
+import os
+
+# Force UTF-8 on stdout/stderr for Windows terminals (cp1252 default crashes
+# on emojis, em-dashes, and any non-ASCII output the CLI prints).
+# Python 3.7+ supports reconfigure(); older versions get a no-op.
+try:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+
+def main():
+    """Entry point that delegates to comms_v4.py within the package."""
+    # Find comms_v4.py — first in package dir, then in repo root
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    repo_root = os.path.dirname(pkg_dir)
+
+    for candidate in [
+        os.path.join(pkg_dir, "comms_v4.py"),
+        os.path.join(repo_root, "comms_v4.py"),
+    ]:
+        if os.path.exists(candidate):
+            sys.argv[0] = candidate
+            # Set __name__ and __file__ for the script
+            globs = {"__name__": "__main__", "__file__": candidate}
+            # Force UTF-8 on Windows (cp1252 default crashes on non-ASCII)
+            with open(candidate, encoding="utf-8") as f:
+                exec(compile(f.read(), candidate, "exec"), globs)
+            return
+
+    print("[meshcode] ERROR: comms_v4.py not found. Reinstall: pip install meshcode")
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

meshcode-2.11.94/meshcode/compat.py

@@ -0,0 +1,174 @@
+"""Claude Code version compatibility matrix.
+
+Tracks known-good and known-bad Claude Code versions so the SDK can
+adjust behavior at runtime and warn users about regressions.
+
+HEARTBEAT THRESHOLD CONTRACT (reference):
+  clear(60) < guard(90) < decay(180) < display(300) < client(600)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import shutil
+from typing import Optional, Dict, List, Tuple
+
+
+# ============================================================
+# COMPATIBILITY MATRIX
+# ============================================================
+# Each entry: version_prefix -> {status, issues[], mitigations[]}
+# status: "safe", "degraded", "broken"
+# Versions not listed are assumed "unknown" (treated as safe with warning).
+
+MATRIX: Dict[str, Dict] = {
+    # Known-good versions
+    "2.1.104": {
+        "status": "safe",
+        "issues": [],
+        "mitigations": [],
+    },
+    # ESC/MCP stdio regression range: 2.1.111 through 2.1.119
+    "2.1.111": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe instead of sending cancel notification"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.112": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.113": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.114": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.115": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.116": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.117": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.118": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+    "2.1.119": {
+        "status": "broken",
+        "issues": ["ESC closes MCP stdio pipe (same as 2.1.111)"],
+        "mitigations": ["Pin to 2.1.104: npm i -g @anthropic-ai/claude-code@2.1.104"],
+    },
+}
+
+RECOMMENDED_VERSION = "2.1.104"
+
+
+def detect_cc_version() -> Optional[str]:
+    """Detect installed Claude Code version. Returns version string or None."""
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        return None
+    try:
+        out = subprocess.run(
+            [claude_bin, "--version"],
+            capture_output=True, text=True, timeout=5,
+        )
+        # Output like "2.1.104 (Claude Code)" or "Claude Code 2.1.104"
+        text = out.stdout.strip()
+        for part in text.split():
+            # Find the version-like token
+            if part[0].isdigit() and "." in part:
+                return part.strip("()")
+    except Exception:
+        pass
+    return None
+
+
+def lookup(version: str) -> Dict:
+    """Look up a version in the matrix. Returns entry or unknown default."""
+    if version in MATRIX:
+        return MATRIX[version]
+    # Try prefix match (e.g., "2.1.104" matches "2.1.104-beta")
+    for key in MATRIX:
+        if version.startswith(key):
+            return MATRIX[key]
+    return {
+        "status": "unknown",
+        "issues": [],
+        "mitigations": [],
+    }
+
+
+def check() -> Tuple[str, str, Dict]:
+    """Check current CC version against matrix.
+
+    Returns: (version_str, status, entry_dict)
+    """
+    version = detect_cc_version()
+    if not version:
+        return ("not found", "unknown", {
+            "status": "unknown",
+            "issues": ["Claude Code not found in PATH"],
+            "mitigations": ["Install: npm i -g @anthropic-ai/claude-code"],
+        })
+    entry = lookup(version)
+    return (version, entry["status"], entry)
+
+
+def get_runtime_adjustments(version: str) -> Dict:
+    """Return runtime parameter adjustments for a given CC version.
+
+    These can be applied by the MCP server to mitigate known issues.
+    """
+    entry = lookup(version)
+    adjustments = {}
+
+    if entry["status"] == "broken":
+        # ESC kills MCP: use shorter wait timeouts so if MCP dies,
+        # it restarts faster and doesn't miss too many messages.
+        adjustments["wait_timeout_cap"] = 10  # seconds (default 20)
+        adjustments["heartbeat_interval"] = 15  # seconds (default 30)
+        adjustments["warn_on_boot"] = True
+
+    elif entry["status"] == "degraded":
+        adjustments["heartbeat_interval"] = 20  # slightly more aggressive
+        adjustments["warn_on_boot"] = True
+
+    return adjustments
+
+
+def format_report(version: str, entry: Dict) -> str:
+    """Format a human-readable compatibility report."""
+    lines = []
+    lines.append(f"  Claude Code version: {version}")
+    lines.append(f"  Status: {entry.get('status', 'unknown').upper()}")
+    lines.append(f"  Recommended: {RECOMMENDED_VERSION}")
+    if entry.get("issues"):
+        lines.append("")
+        lines.append("  Known issues:")
+        for issue in entry["issues"]:
+            lines.append(f"    - {issue}")
+    if entry.get("mitigations"):
+        lines.append("")
+        lines.append("  Fixes:")
+        for m in entry["mitigations"]:
+            lines.append(f"    - {m}")
+    if entry.get("status") == "safe":
+        lines.append("  No known issues.")
+    return "\n".join(lines)

meshcode-2.11.94/meshcode/error_hints.py

@@ -0,0 +1,74 @@
+"""Smart error messages — maps common error patterns to actionable fix commands.
+
+Usage:
+    from meshcode.error_hints import hint_for_error
+    print(hint_for_error("agent not found"))
+    # → "Run: meshcode register <project> <agent> <role>"
+"""
+
+_HINTS = [
+    # Auth errors
+    ("invalid api_key", "Run: meshcode login <api_key> to set your credentials"),
+    ("api key", "Run: meshcode login <api_key> to refresh credentials"),
+    ("auth_failed", "Run: meshcode login to re-authenticate"),
+    ("forbidden", "You don't have permission. Check: meshcode doctor"),
+    ("not authenticated", "Run: meshcode login <api_key>"),
+
+    # Agent errors
+    ("agent not found", "Run: meshcode register <project> <agent_name> <role>"),
+    ("agent.*not registered", "Run: meshcode register <project> <agent_name> <role>"),
+
+    # Project errors
+    ("project.*not found", "Check project name with: meshcode projects"),
+    ("no projects found", "Create one at meshcode.io/dashboard or: meshcode init <project_name>"),
+
+    # Network errors
+    ("circuit breaker open", "Supabase is temporarily unavailable. Wait 30s and retry. Details: meshcode doctor"),
+    ("connection refused", "Check internet connection. If persists: meshcode doctor"),
+    ("network error", "Check internet connection. If persists: meshcode doctor"),
+    ("timeout", "Request timed out. Check connection: meshcode doctor"),
+
+    # MCP errors
+    ("MCP server crashed", "Restart: meshcode run <agent>"),
+    ("stdin EOF", "MCP pipe closed. Restart the MCP server or Claude Code session"),
+    ("mcp.*failed", "Check MCP config: meshcode doctor"),
+
+    # Task errors
+    ("task.*already claimed", "This task is being worked on. Try: meshcode tasks to see available tasks"),
+    ("task not found", "Check task ID. List tasks: meshcode tasks"),
+
+    # Config errors
+    ("comms_v4.py not found", "Reinstall: pip install --upgrade meshcode"),
+    ("\.mcp\.json", "Run: meshcode setup <project> <agent> to create config"),
+
+    # Token errors
+    ("token expired", "Generate a new token from the dashboard"),
+    ("token already used", "Generate a new token from the dashboard"),
+]
+
+
+def hint_for_error(error_msg: str) -> str:
+    """Return an actionable fix suggestion for a given error message.
+
+    Returns empty string if no hint matches.
+    """
+    import re
+    lower = error_msg.lower()
+    for pattern, hint in _HINTS:
+        if re.search(pattern, lower):
+            return hint
+    return ""
+
+
+def format_error(error_msg: str, prefix: str = "[meshcode]") -> str:
+    """Format an error with an actionable hint if available.
+
+    Example output:
+        [meshcode] ERROR: agent not found
+        [meshcode] Fix: Run: meshcode register <project> <agent_name> <role>
+    """
+    lines = [f"{prefix} ERROR: {error_msg}"]
+    hint = hint_for_error(error_msg)
+    if hint:
+        lines.append(f"{prefix} Fix: {hint}")
+    return "\n".join(lines)

meshcode-2.11.94/meshcode/exceptions.py

@@ -0,0 +1,52 @@
+"""MeshCode exception hierarchy.
+
+All SDK-specific errors inherit from :class:`MeshCodeError` so callers can
+catch a single base class, or narrow down to the specific failure mode.
+
+CLI entry points (cli.py, launcher.py, server.py boot) catch these and
+convert to ``sys.exit(2)`` so end-user behaviour is unchanged.
+"""
+
+
+class MeshCodeError(Exception):
+    """Base exception for all MeshCode SDK errors."""
+
+
+class AuthError(MeshCodeError):
+    """Authentication or API-key related failure.
+
+    Raised when:
+    - No API key is found in the keychain or environment
+    - The secrets module cannot be loaded
+    - An API key is rejected by the server
+    """
+
+
+class RPCError(MeshCodeError):
+    """A Supabase RPC call returned an error payload.
+
+    Attributes:
+        rpc_name:  Name of the RPC function that failed (if known).
+        detail:    Server-provided error message.
+    """
+
+    def __init__(self, message: str, *, rpc_name: str = "", detail: str = ""):
+        super().__init__(message)
+        self.rpc_name = rpc_name
+        self.detail = detail
+
+
+class MeshCodeTimeoutError(MeshCodeError):
+    """A network or RPC call timed out.
+
+    Named ``MeshCodeTimeoutError`` to avoid shadowing the builtin
+    :class:`TimeoutError`.
+    """
+
+
+class MeshCodeConnectionError(MeshCodeError):
+    """Could not reach the MeshCode / Supabase backend.
+
+    Named ``MeshCodeConnectionError`` to avoid shadowing the builtin
+    :class:`ConnectionError`.
+    """