meshcode 2.10.56__tar.gz → 2.10.57__tar.gz

{meshcode-2.10.56 → meshcode-2.10.57}/PKG-INFO

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

{meshcode-2.10.56 → meshcode-2.10.57}/meshcode/__init__.py

@@ -1,5 +1,14 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.10.56"
+__version__ = "2.10.57"
+
+# Exception hierarchy — eagerly imported (lightweight, no deps)
+from meshcode.exceptions import (  # noqa: F401
+    MeshCodeError,
+    AuthError,
+    RPCError,
+    MeshCodeTimeoutError,
+    MeshCodeConnectionError,
+)
 
 # Public API — lazy imports to avoid heavy deps at import time
 def __getattr__(name):
@@ -42,6 +51,12 @@ _SECRETS_EXPORTS = {
 __all__ = [
     "__version__",
     "backend",
+    # Exceptions
+    "MeshCodeError",
+    "AuthError",
+    "RPCError",
+    "MeshCodeTimeoutError",
+    "MeshCodeConnectionError",
     # Messaging
     "send_message",
     "read_inbox",

meshcode-2.10.57/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`.
+    """

{meshcode-2.10.56 → meshcode-2.10.57}/meshcode/meshcode_mcp/server.py

@@ -922,7 +922,7 @@ def _acquire_lease() -> bool:
                             "p_api_key": api_key,
                             "p_project_id": _PROJECT_ID,
                             "p_agent_name": AGENT_NAME,
-                            "p_instance_id": r.get("held_by", "unknown"),
+                            "p_instance_id": r.get("current_instance", r.get("held_by", "unknown")),
                         })
                     except Exception:
                         # Force clear via direct update
@@ -3900,6 +3900,7 @@ def meshcode_health() -> Dict[str, Any]:
 
     # Realtime status
     health["realtime_connected"] = _REALTIME.is_connected if _REALTIME else False
+    health["realtime_subscribed"] = _REALTIME.is_subscribed if _REALTIME else False
 
     # Process uptime
     try:
@@ -3909,6 +3910,20 @@ def meshcode_health() -> Dict[str, Any]:
     except Exception:
         health["uptime_seconds"] = "unknown (psutil not available)"
 
+    # Server-side system health (aggregate metrics from DB)
+    try:
+        sys_health = be.sb_rpc("mc_system_health", {})
+        if isinstance(sys_health, dict) and sys_health.get("ok"):
+            health["system"] = {
+                "active_agents": sys_health.get("active_agent_count"),
+                "stale_agents": sys_health.get("stale_agent_count"),
+                "message_delivery_rate": sys_health.get("message_delivery_rate"),
+                "messages_1h": sys_health.get("total_messages_1h"),
+                "failed_rpcs_1h": sys_health.get("failed_rpc_count_1h"),
+            }
+    except Exception:
+        pass  # mc_system_health may not be deployed yet
+
     return health
 
 

{meshcode-2.10.56 → meshcode-2.10.57}/meshcode/setup_clients.py

@@ -22,6 +22,8 @@ import sys
 from pathlib import Path
 from typing import Dict, Any, Optional
 
+from meshcode.exceptions import AuthError, RPCError, MeshCodeConnectionError
+
 
 def _load_credentials(profile: str = "default") -> Dict[str, str]:
     """Load the api key + non-secret metadata for the given keychain profile.
@@ -36,18 +38,18 @@ def _load_credentials(profile: str = "default") -> Dict[str, str]:
         import importlib
         secrets_mod = importlib.import_module("meshcode.secrets")
     except Exception as e:
-        print(f"[meshcode] ERROR: cannot load secrets module: {e}", file=sys.stderr)
-        sys.exit(2)
+        raise AuthError(f"cannot load secrets module: {e}") from e
 
     api_key = secrets_mod.get_api_key(profile=profile)
     if not api_key:
-        print("[meshcode] ERROR: No credentials found. You need to log in first.", file=sys.stderr)
-        print("[meshcode]", file=sys.stderr)
-        print("[meshcode]   1. Get your API key at: https://meshcode.io/onboarding", file=sys.stderr)
-        print("[meshcode]      (or https://meshcode.io/settings if you already have an account)", file=sys.stderr)
-        print("[meshcode]   2. Run: meshcode login mc_<your-api-key>", file=sys.stderr)
-        print("[meshcode]   3. Then re-run this command.", file=sys.stderr)
-        sys.exit(2)
+        raise AuthError(
+            "No credentials found. You need to log in first.\n"
+            "\n"
+            "  1. Get your API key at: https://meshcode.io/onboarding\n"
+            "     (or https://meshcode.io/settings if you already have an account)\n"
+            "  2. Run: meshcode login mc_<your-api-key>\n"
+            "  3. Then re-run this command."
+        )
 
     meta_path = Path.home() / ".meshcode" / "profile_meta.json"
     meta: Dict[str, Any] = {"api_key": api_key}
@@ -119,19 +121,24 @@ def _resolve_project_id(api_key: str, project: str, sb: Dict[str, str]) -> str:
             if isinstance(data, dict) and data.get("project_id"):
                 return data["project_id"]
             if isinstance(data, dict) and data.get("error"):
-                print(f"[meshcode] ERROR: could not resolve project '{project}': {data['error']}", file=sys.stderr)
-                # Try to suggest the user's actual projects
-                _suggest_projects(api_key, sb)
-                sys.exit(2)
+                # Build a helpful message including the user's actual projects
+                hint = _suggest_projects_str(api_key, sb)
+                msg = f"could not resolve project '{project}': {data['error']}"
+                if hint:
+                    msg += f"\n{hint}"
+                raise RPCError(msg, rpc_name="mc_resolve_project", detail=data["error"])
+    except (RPCError, AuthError):
+        raise
     except Exception as e:
-        print(f"[meshcode] ERROR: could not resolve project '{project}': {e}", file=sys.stderr)
-        print(f"[meshcode] Check your API key and project name. Get help at https://meshcode.io/docs", file=sys.stderr)
-        sys.exit(2)
+        raise MeshCodeConnectionError(
+            f"could not resolve project '{project}': {e}\n"
+            f"Check your API key and project name. Get help at https://meshcode.io/docs"
+        ) from e
     return ""
 
 
-def _suggest_projects(api_key: str, sb: dict):
-    """Try to list the user's projects to help with typos."""
+def _suggest_projects_str(api_key: str, sb: dict) -> str:
+    """Try to list the user's projects; return a hint string (or empty)."""
     try:
         from urllib.request import Request as _Req, urlopen as _urlopen
         body = json.dumps({"p_api_key": api_key}).encode()
@@ -149,11 +156,21 @@ def _suggest_projects(api_key: str, sb: dict):
             data = json.loads(resp.read().decode())
         projects = data.get("projects", []) if isinstance(data, dict) else []
         if projects:
-            print(f"[meshcode] Your projects:", file=sys.stderr)
+            lines = ["Your projects:"]
             for p in projects:
-                print(f"[meshcode]   - {p['name']}", file=sys.stderr)
+                lines.append(f"  - {p['name']}")
+            return "\n".join(lines)
     except Exception:
         pass
+    return ""
+
+
+def _suggest_projects(api_key: str, sb: dict):
+    """Print the user's projects to stderr (CLI convenience wrapper)."""
+    hint = _suggest_projects_str(api_key, sb)
+    if hint:
+        for line in hint.splitlines():
+            print(f"[meshcode] {line}", file=sys.stderr)
 
 
 def _build_server_block(project: str, project_id: str, agent: str, role: str,
@@ -414,7 +431,11 @@ def setup_workspace(project: str, agent: str, role: str = "",
             print(f"[meshcode]   This profile is created by `meshcode join <token>`.", file=sys.stderr)
         return 2
 
-    project_id = _resolve_project_id(api_key, project, sb)
+    try:
+        project_id = _resolve_project_id(api_key, project, sb)
+    except (RPCError, MeshCodeConnectionError, AuthError) as exc:
+        print(f"[meshcode] ERROR: {exc}", file=sys.stderr)
+        return 2
 
     server_id = f"meshcode-{project}-{agent}"
     server_block = _build_server_block(project, project_id, agent, role, api_key, sb,
@@ -565,10 +586,18 @@ def setup_global(client: str, project: str, agent: str, role: str = "") -> int:
         print(f"[meshcode] ERROR: Unknown client '{client}'. Supported: {', '.join(CLIENT_CONFIG_PATHS)}", file=sys.stderr)
         return 2
 
-    creds = _load_credentials()
+    try:
+        creds = _load_credentials()
+    except AuthError as exc:
+        print(f"[meshcode] ERROR: {exc}", file=sys.stderr)
+        return 2
     sb = _load_supabase_env()
     api_key = creds.get("api_key", "")
-    project_id = _resolve_project_id(api_key, project, sb)
+    try:
+        project_id = _resolve_project_id(api_key, project, sb)
+    except (RPCError, MeshCodeConnectionError) as exc:
+        print(f"[meshcode] ERROR: {exc}", file=sys.stderr)
+        return 2
 
     os_name = platform.system()
     config_path = CLIENT_CONFIG_PATHS[client].get(os_name)

{meshcode-2.10.56 → meshcode-2.10.57}/meshcode.egg-info/PKG-INFO

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

{meshcode-2.10.56 → meshcode-2.10.57}/meshcode.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ meshcode/ascii_art.py
 meshcode/cli.py
 meshcode/comms_v4.py
 meshcode/compat.py
+meshcode/exceptions.py
 meshcode/invites.py
 meshcode/launcher.py
 meshcode/launcher_install.py
@@ -31,6 +32,7 @@ meshcode/meshcode_mcp/test_server_wrapper.py
 tests/test_core.py
 tests/test_cross_agent_messaging.py
 tests/test_esc_deaf_state.py
+tests/test_exceptions.py
 tests/test_realtime_event_freshness.py
 tests/test_rpc_migrations.py
 tests/test_status_enum_coverage.py

{meshcode-2.10.56 → meshcode-2.10.57}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshcode"
-version = "2.10.56"
+version = "2.10.57"
 description = "Real-time communication between AI agents — Supabase-backed CLI"
 readme = "README.md"
 license = {text = "MIT"}

meshcode-2.10.57/tests/test_exceptions.py

@@ -0,0 +1,107 @@
+"""
+Exception Hierarchy Tests
+=========================
+Validates the custom exception classes exported by meshcode.
+
+Usage:
+    pytest tests/test_exceptions.py -v
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+class TestExceptionHierarchy:
+    """All custom exceptions inherit from MeshCodeError."""
+
+    def test_base_is_exception(self):
+        from meshcode.exceptions import MeshCodeError
+        assert issubclass(MeshCodeError, Exception)
+
+    def test_auth_error_inherits_base(self):
+        from meshcode.exceptions import AuthError, MeshCodeError
+        assert issubclass(AuthError, MeshCodeError)
+
+    def test_rpc_error_inherits_base(self):
+        from meshcode.exceptions import RPCError, MeshCodeError
+        assert issubclass(RPCError, MeshCodeError)
+
+    def test_timeout_error_inherits_base(self):
+        from meshcode.exceptions import MeshCodeTimeoutError, MeshCodeError
+        assert issubclass(MeshCodeTimeoutError, MeshCodeError)
+
+    def test_connection_error_inherits_base(self):
+        from meshcode.exceptions import MeshCodeConnectionError, MeshCodeError
+        assert issubclass(MeshCodeConnectionError, MeshCodeError)
+
+    def test_catch_all_works(self):
+        """Single `except MeshCodeError` catches all subclasses."""
+        from meshcode.exceptions import (
+            MeshCodeError, AuthError, RPCError,
+            MeshCodeTimeoutError, MeshCodeConnectionError,
+        )
+        for exc_class in [AuthError, RPCError, MeshCodeTimeoutError, MeshCodeConnectionError]:
+            try:
+                raise exc_class("test")
+            except MeshCodeError:
+                pass  # Expected
+            except Exception:
+                assert False, f"{exc_class.__name__} not caught by MeshCodeError"
+
+
+class TestRPCErrorAttributes:
+    """RPCError carries structured metadata."""
+
+    def test_rpc_name_attribute(self):
+        from meshcode.exceptions import RPCError
+        e = RPCError("test", rpc_name="mc_heartbeat")
+        assert e.rpc_name == "mc_heartbeat"
+
+    def test_detail_attribute(self):
+        from meshcode.exceptions import RPCError
+        e = RPCError("test", detail="not found")
+        assert e.detail == "not found"
+
+    def test_default_attributes_empty(self):
+        from meshcode.exceptions import RPCError
+        e = RPCError("test")
+        assert e.rpc_name == ""
+        assert e.detail == ""
+
+    def test_str_is_message(self):
+        from meshcode.exceptions import RPCError
+        e = RPCError("something went wrong")
+        assert str(e) == "something went wrong"
+
+
+class TestExceptionImportsFromPackage:
+    """Exceptions are importable from the top-level meshcode package."""
+
+    def test_import_from_meshcode(self):
+        from meshcode import (
+            MeshCodeError, AuthError, RPCError,
+            MeshCodeTimeoutError, MeshCodeConnectionError,
+        )
+        assert MeshCodeError is not None
+
+    def test_in_all(self):
+        import meshcode
+        for name in ["MeshCodeError", "AuthError", "RPCError",
+                     "MeshCodeTimeoutError", "MeshCodeConnectionError"]:
+            assert name in meshcode.__all__, f"{name} missing from __all__"
+
+
+class TestNoShadowBuiltins:
+    """Custom names don't shadow Python builtins."""
+
+    def test_timeout_name_is_prefixed(self):
+        from meshcode.exceptions import MeshCodeTimeoutError
+        assert MeshCodeTimeoutError.__name__ == "MeshCodeTimeoutError"
+        assert MeshCodeTimeoutError is not TimeoutError
+
+    def test_connection_name_is_prefixed(self):
+        from meshcode.exceptions import MeshCodeConnectionError
+        assert MeshCodeConnectionError.__name__ == "MeshCodeConnectionError"
+        assert MeshCodeConnectionError is not ConnectionError

{meshcode-2.10.56 → meshcode-2.10.57}/tests/test_rpc_migrations.py

@@ -76,6 +76,14 @@ CRITICAL_RPCS: list[RPCSpec] = [
         description="Returns effective status based on heartbeat freshness (NOT YET IMPLEMENTED)",
         exists=False,
     ),
+    RPCSpec(
+        name="mc_system_health",
+        schema="public",
+        params=[],
+        return_type="jsonb",
+        required_in_body=["mc_agents", "mc_messages", "stale_agent_count", "message_delivery_rate"],
+        description="Returns system health metrics (active/stale agents, delivery rate, errors)",
+    ),
     RPCSpec(
         name="mc_get_mesh_graph",
         schema="public",
@@ -187,7 +195,7 @@ def parse_params(signature: str) -> list[tuple[str, str]]:
 
 # ─── Tests ─────────────────────────────────────────────────────────────────────
 
-class TestResults:
+class CheckResults:
     def __init__(self):
         self.passed = 0
         self.failed = 0
@@ -208,7 +216,7 @@ class TestResults:
         print(f"  ⊘ {msg}")
 
 
-def test_function_exists(spec: RPCSpec, results: TestResults) -> Optional[tuple[str, str, str]]:
+def check_function_exists(spec: RPCSpec, results: CheckResults) -> Optional[tuple[str, str, str]]:
     """Test 1: Verify function exists in migrations."""
     if not spec.exists:
         results.skip(f"{spec.name}: known not-yet-implemented")
@@ -224,7 +232,7 @@ def test_function_exists(spec: RPCSpec, results: TestResults) -> Optional[tuple[
         return None
 
 
-def test_function_signature(spec: RPCSpec, signature: str, results: TestResults):
+def check_function_signature(spec: RPCSpec, signature: str, results: CheckResults):
     """Test 2: Verify function has expected parameters."""
     if not spec.exists:
         return
@@ -249,7 +257,7 @@ def test_function_signature(spec: RPCSpec, signature: str, results: TestResults)
             results.fail(f"{spec.name}: missing required param '{exp_name}'")
 
 
-def test_function_body(spec: RPCSpec, body: str, results: TestResults):
+def check_function_body(spec: RPCSpec, body: str, results: CheckResults):
     """Test 3: Verify function body contains required patterns."""
     if not spec.exists:
         return
@@ -261,7 +269,7 @@ def test_function_body(spec: RPCSpec, body: str, results: TestResults):
             results.fail(f"{spec.name}: body MISSING required pattern '{pattern}'")
 
 
-def test_return_type(spec: RPCSpec, body: str, results: TestResults):
+def check_return_type(spec: RPCSpec, body: str, results: CheckResults):
     """Test 4: Verify function returns correct type."""
     if not spec.exists:
         return
@@ -283,7 +291,7 @@ def test_return_type(spec: RPCSpec, body: str, results: TestResults):
         results.fail(f"{spec.name}: could not find RETURNS clause")
 
 
-def test_no_security_antipatterns(spec: RPCSpec, body: str, results: TestResults):
+def check_no_security_antipatterns(spec: RPCSpec, body: str, results: CheckResults):
     """Test 5: Check for known security anti-patterns in function body."""
     if not spec.exists:
         return
@@ -301,7 +309,7 @@ def test_no_security_antipatterns(spec: RPCSpec, body: str, results: TestResults
         results.ok(f"{spec.name}: no unsafe EXECUTE patterns")
 
 
-def test_error_handling(spec: RPCSpec, body: str, results: TestResults):
+def check_error_handling(spec: RPCSpec, body: str, results: CheckResults):
     """Test 6: Verify function has error handling (returns error JSON, not raw exception)."""
     if not spec.exists:
         return
@@ -333,21 +341,21 @@ def run_all_tests():
     print("=" * 70)
     print()
 
-    results = TestResults()
+    results = CheckResults()
 
     for spec in CRITICAL_RPCS:
         print(f"\n─── {spec.name} ({'NOT IMPLEMENTED' if not spec.exists else spec.description}) ───")
 
-        found = test_function_exists(spec, results)
+        found = check_function_exists(spec, results)
         if not found:
             continue
 
         file_name, signature, body = found
-        test_function_signature(spec, signature, results)
-        test_return_type(spec, body, results)
-        test_function_body(spec, body, results)
-        test_no_security_antipatterns(spec, body, results)
-        test_error_handling(spec, body, results)
+        check_function_signature(spec, signature, results)
+        check_return_type(spec, body, results)
+        check_function_body(spec, body, results)
+        check_no_security_antipatterns(spec, body, results)
+        check_error_handling(spec, body, results)
 
     # Summary
     print("\n" + "=" * 70)