meshcode 1.2.6__tar.gz → 1.4.0__tar.gz

{meshcode-1.2.6 → meshcode-1.4.0}/PKG-INFO

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

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode/__init__.py

@@ -1,2 +1,2 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "1.2.6"
+__version__ = "1.4.0"

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode/comms_v4.py

@@ -1888,17 +1888,25 @@ if __name__ == "__main__":
         disconnect_terminal(proj, name)
 
     elif cmd == "setup":
-        if len(sys.argv) < 5:
-            print("Usage: meshcode setup <client> <project> <agent> [role]")
-            print("Clients: claude-code, cursor, cline, claude-desktop")
+        # Two forms supported:
+        #   meshcode setup <project> <agent> [role]            → workspace flow (1.3+)
+        #   meshcode setup <client> <project> <agent> [role]   → legacy global flow
+        # Dispatched by setup_clients.setup() which detects which form was used.
+        import importlib
+        _setup_dispatcher = importlib.import_module("meshcode.setup_clients").setup
+        sys.exit(_setup_dispatcher(*sys.argv[2:]))
+
+    elif cmd == "run":
+        # meshcode run <agent> [--project <name>] [--editor claude|cursor|code]
+        if len(sys.argv) < 3:
+            print("Usage: meshcode run <agent> [--project <name>] [--editor claude|cursor|code]")
             sys.exit(1)
-        client = sys.argv[2]
-        project = sys.argv[3]
-        agent = sys.argv[4]
-        role = sys.argv[5] if len(sys.argv) > 5 else ""
+        agent = sys.argv[2]
+        proj_override = flags.get("project")
+        editor_override = flags.get("editor")
         import importlib
-        _setup_client = importlib.import_module("meshcode.setup_clients").setup
-        sys.exit(_setup_client(client, project, agent, role))
+        _run = importlib.import_module("meshcode.run_agent").run
+        sys.exit(_run(agent, project=proj_override, editor_override=editor_override))
 
     elif cmd == "login":
         key = sys.argv[2] if len(sys.argv) > 2 else ""

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode/meshcode_mcp/realtime.py

@@ -44,6 +44,9 @@ class RealtimeListener:
         self._task: Optional[asyncio.Task] = None
         self._stop = asyncio.Event()
         self._connected = False
+        # Event fired whenever a new message is appended to the queue.
+        # meshcode_wait awaits this instead of polling → zero-cost idle.
+        self.message_event = asyncio.Event()
 
     @property
     def ws_url(self) -> str:
@@ -163,6 +166,11 @@ class RealtimeListener:
                         "id": record.get("id"),
                     }
                     self.queue.append(enriched)
+                    # Wake any meshcode_wait blocked on this event.
+                    try:
+                        self.message_event.set()
+                    except Exception:
+                        pass
                     log.info(f"new message from {enriched['from']}")
                     if self.notify_callback:
                         try:
@@ -174,8 +182,26 @@ class RealtimeListener:
         """Pop and return all queued messages."""
         out = list(self.queue)
         self.queue.clear()
+        # Queue is empty → reset the wake event so the next wait blocks again.
+        try:
+            self.message_event.clear()
+        except Exception:
+            pass
         return out
 
+    async def wait_for_message(self, timeout: Optional[float] = None) -> bool:
+        """Block until a new message lands in the queue (or timeout).
+
+        Returns True if woken by a message, False on timeout. This is the
+        core of the zero-cost idle loop: while awaiting, the event loop
+        does ZERO work — no polling, no Supabase calls, no token cost.
+        """
+        try:
+            await asyncio.wait_for(self.message_event.wait(), timeout=timeout)
+            return True
+        except asyncio.TimeoutError:
+            return False
+
     @property
     def is_connected(self) -> bool:
         return self._connected

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode/meshcode_mcp/server.py

@@ -12,8 +12,75 @@ import json
 import logging
 import os
 import sys
+from collections import deque
 from contextlib import asynccontextmanager
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
+
+
+# ============================================================
+# Dedupe: track IDs of messages we've already returned from
+# meshcode_wait / meshcode_check so the same row doesn't show
+# up twice when realtime + polled paths race.
+# ============================================================
+_SEEN_MSG_IDS: set = set()
+_SEEN_MSG_ORDER: deque = deque()
+_SEEN_MSG_CAP = 1000
+
+
+def _seen_key(msg: Dict[str, Any]) -> str:
+    """Build a dedupe key. Prefer the real row id; fall back to a synthetic."""
+    mid = msg.get("id")
+    if mid:
+        return str(mid)
+    payload = msg.get("payload") or {}
+    try:
+        payload_str = json.dumps(payload, sort_keys=True, default=str)[:50]
+    except Exception:
+        payload_str = str(payload)[:50]
+    return f"{msg.get('from') or msg.get('from_agent')}|{msg.get('ts') or msg.get('created_at')}|{payload_str}"
+
+
+def _mark_seen(key: str) -> None:
+    if key in _SEEN_MSG_IDS:
+        return
+    _SEEN_MSG_IDS.add(key)
+    _SEEN_MSG_ORDER.append(key)
+    while len(_SEEN_MSG_ORDER) > _SEEN_MSG_CAP:
+        old = _SEEN_MSG_ORDER.popleft()
+        _SEEN_MSG_IDS.discard(old)
+
+
+def _filter_and_mark(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Drop already-seen messages; mark the rest as seen."""
+    out = []
+    for m in messages:
+        k = _seen_key(m)
+        if k in _SEEN_MSG_IDS:
+            continue
+        _mark_seen(k)
+        out.append(m)
+    return out
+
+
+def _split_messages(messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Split a list of normalized message dicts into messages / acks / done_signals."""
+    real: List[Dict[str, Any]] = []
+    acks: List[Dict[str, Any]] = []
+    dones: List[Dict[str, Any]] = []
+    for m in messages:
+        t = m.get("type", "msg")
+        if t == "ack":
+            acks.append(m)
+        elif t == "done":
+            dones.append(m)
+        else:
+            real.append(m)
+    return {
+        "messages": real,
+        "acks": acks,
+        "done_signals": dones,
+        "count": len(real),
+    }
 
 from . import backend as be
 from .realtime import RealtimeListener
@@ -78,12 +145,85 @@ if isinstance(_register_result, dict) and _register_result.get("error"):
     print(f"[meshcode-mcp] WARNING: register failed: {_register_result['error']}", file=sys.stderr)
 
 # Flip to online so the dashboard reflects the live MCP session.
-# Without this the agent stays in 'needs_setup' / 'offline' even though
-# heartbeat is running. The set_status helper updates status + last_heartbeat.
-try:
-    be.set_status(_PROJECT_ID, AGENT_NAME, "online", "MCP session active")
-except Exception as _e:
-    print(f"[meshcode-mcp] WARNING: could not flip status to online: {_e}", file=sys.stderr)
+# Use the SECURITY DEFINER RPC (mc_agent_set_status_by_api_key) so we
+# bypass RLS — the publishable key has no JWT context and cannot UPDATE
+# mc_agents directly. The RPC validates ownership via api_key.
+def _flip_status(status: str, task: str = "") -> bool:
+    api_key = os.environ.get("MESHCODE_API_KEY", "")
+    if not api_key:
+        # Last-resort fallback: try the direct PATCH (may be denied by RLS)
+        try:
+            be.set_status(_PROJECT_ID, AGENT_NAME, status, task)
+            return True
+        except Exception:
+            return False
+    try:
+        r = be.sb_rpc("mc_agent_set_status_by_api_key", {
+            "p_api_key": api_key,
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+            "p_status": status,
+            "p_task": task,
+        })
+        if isinstance(r, dict) and r.get("ok"):
+            return True
+        if isinstance(r, dict) and r.get("error"):
+            log.warning(f"set_status RPC: {r['error']}")
+        return False
+    except Exception as e:
+        log.warning(f"set_status RPC threw: {e}")
+        return False
+
+if not _flip_status("online", "MCP session active"):
+    print(f"[meshcode-mcp] WARNING: could not flip status to online", file=sys.stderr)
+
+
+# ============================================================
+# Single-instance lease — prevent split-brain when two windows
+# run `meshcode run <same-agent>` simultaneously.
+# ============================================================
+import uuid as _uuid
+_INSTANCE_ID = f"mcp-{_uuid.uuid4().hex[:12]}"
+
+def _acquire_lease() -> bool:
+    api_key = os.environ.get("MESHCODE_API_KEY", "")
+    if not api_key:
+        return True  # legacy clients without api_key skip lease check
+    try:
+        r = be.sb_rpc("mc_acquire_agent_lease", {
+            "p_api_key": api_key,
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+            "p_instance_id": _INSTANCE_ID,
+        })
+        if isinstance(r, dict) and r.get("ok"):
+            return True
+        if isinstance(r, dict) and r.get("error"):
+            print(f"[meshcode-mcp] LEASE DENIED: {r['error']}", file=sys.stderr)
+            print(f"[meshcode-mcp] Another window is already running this agent.", file=sys.stderr)
+            print(f"[meshcode-mcp] Close the other window first, or use a different agent name.", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"[meshcode-mcp] WARNING: lease RPC failed: {e}", file=sys.stderr)
+        return True  # don't hard-fail on transient network issues
+
+if not _acquire_lease():
+    sys.exit(2)
+
+
+def _release_lease() -> None:
+    api_key = os.environ.get("MESHCODE_API_KEY", "")
+    if not api_key:
+        return
+    try:
+        be.sb_rpc("mc_release_agent_lease", {
+            "p_api_key": api_key,
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+            "p_instance_id": _INSTANCE_ID,
+        })
+    except Exception:
+        pass
 
 
 # ============================================================
@@ -155,10 +295,19 @@ YOUR DEFAULT BEHAVIOR LOOP (do this without being asked):
    user prompt. Read it, decide if it requires action or a reply, take
    action, send a reply via meshcode_send if appropriate, then call
    meshcode_wait AGAIN to keep listening.
-5. When meshcode_wait returns timed_out (no message in 4 min), call it
-   AGAIN immediately. Do not return to the user. The loop is your
-   default state — you are a long-running mesh agent, not a one-shot
-   chatbot.
+5. When meshcode_wait returns timed_out, call it AGAIN — but apply
+   TOKEN-EFFICIENT WAIT BACKOFF: double the previous timeout each
+   consecutive timeout (60 → 120 → 240 → 480 → 960 → 1800s, cap at
+   1800). Reset to 60s as soon as you receive ANY mesh message. Do
+   not return to the user. The loop is your default state — you are
+   a long-running mesh agent, not a one-shot chatbot.
+
+6. GLOBAL DONE: when ANY agent (typically commander) calls
+   meshcode_done(reason), every other agent's meshcode_wait returns
+   with {got_done: true, reason}. Treat this as "task complete, exit
+   the loop". Do NOT call meshcode_wait again. Return cleanly to the
+   user with a summary of what the mesh accomplished. Stay quiet
+   until the user gives a new task.
 
 YOU SHOULD ONLY BREAK OUT OF THE meshcode_wait LOOP IF:
 - The human user explicitly says "stop" or pressed Ctrl+C.
@@ -188,6 +337,7 @@ YOUR FIRST ACTIONS WHEN THIS SESSION STARTS:
 
 AVAILABLE MESH TOOLS (all from this MCP server):
   meshcode_wait        — block until a mesh message arrives (your idle state)
+  meshcode_done        — broadcast a GLOBAL DONE to break every agent out of wait
   meshcode_send        — send a message to another mesh agent
   meshcode_check       — non-blocking peek at the inbox count
   meshcode_read        — drain inbox, mark messages read
@@ -257,13 +407,19 @@ async def lifespan(_app):
     try:
         yield {"realtime": _REALTIME}
     finally:
-        log.info("lifespan shutdown — stopping heartbeat + realtime")
+        log.info("lifespan shutdown — stopping heartbeat + realtime + releasing lease")
         hb_task.cancel()
         try:
             await hb_task
         except asyncio.CancelledError:
             pass
         await _REALTIME.stop()
+        # Flip to offline + release lease so the dashboard reflects reality
+        # within seconds (not waiting for the 30s cron to notice).
+        try:
+            _release_lease()
+        except Exception as _e:
+            log.warning(f"could not release lease: {_e}")
 
 
 # ============================================================
@@ -286,13 +442,24 @@ except Exception:
 # ----------------- TOOLS -----------------
 
 @mcp.tool()
-def meshcode_send(to: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+def meshcode_send(to: str, message: Any) -> Dict[str, Any]:
     """Send a message to another agent in the meshwork.
 
+    If you only have plain text, just pass it as a string and it will be
+    wrapped as {text: ...} automatically. For protocol payloads (need / done
+    / fyi / blocked), pass a dict.
+
     Args:
         to: Name of the recipient agent.
-        payload: Structured message payload (use protocol keys: need/done/fyi/blocked).
+        message: Either a plain string (auto-wrapped as {"text": message}) or
+            a structured dict payload (use protocol keys: need/done/fyi/blocked).
     """
+    if isinstance(message, str):
+        payload: Dict[str, Any] = {"text": message}
+    elif isinstance(message, dict):
+        payload = message
+    else:
+        payload = {"text": str(message)}
     return be.send_message(_PROJECT_ID, AGENT_NAME, to, payload, msg_type="msg")
 
 
@@ -314,84 +481,141 @@ def meshcode_broadcast(payload: Dict[str, Any]) -> Dict[str, Any]:
 
 @mcp.tool()
 def meshcode_read() -> Dict[str, Any]:
-    """Read all pending (unread) messages for this agent. Marks them as read and ACKs senders."""
-    messages = be.read_inbox(_PROJECT_ID, AGENT_NAME)
-    return {
-        "count": len(messages),
-        "messages": [
-            {
-                "from": m["from_agent"],
-                "type": m.get("type", "msg"),
-                "ts": m.get("created_at"),
-                "payload": m.get("payload", {}),
-            }
-            for m in messages
-        ],
-    }
+    """Read all pending (unread) messages for this agent. Marks them as read and ACKs senders.
+
+    Returns a split shape: `messages` (real msgs), `acks`, and `done_signals`
+    — so you don't have to filter by type yourself.
+    """
+    raw = be.read_inbox(_PROJECT_ID, AGENT_NAME)
+    normalized = [
+        {
+            "from": m["from_agent"],
+            "type": m.get("type", "msg"),
+            "ts": m.get("created_at"),
+            "payload": m.get("payload", {}),
+            "id": m.get("id"),
+        }
+        for m in raw
+    ]
+    deduped = _filter_and_mark(normalized)
+    return _split_messages(deduped)
+
+
+def _detect_global_done(messages: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Return {reason, from} if the list contains a global_done signal, else None."""
+    for m in messages:
+        if m.get("type") == "done":
+            p = m.get("payload") or {}
+            if p.get("type") == "global_done" or p.get("reason"):
+                return {
+                    "reason": p.get("reason"),
+                    "from": p.get("from") or m.get("from"),
+                }
+    return None
 
 
 @mcp.tool()
-async def meshcode_wait(timeout_seconds: int = 240) -> Dict[str, Any]:
+async def meshcode_wait(timeout_seconds: int = 120) -> Dict[str, Any]:
     """LONG-POLL: Block until a new message arrives for this agent (or timeout).
 
-    THIS IS THE AUTONOMOUS LOOP TOOL. Call this whenever you finish any task
-    and want to listen for messages from other agents in the meshwork. The
-    tool BLOCKS inside the MCP server — your turn does not end. When a
-    message arrives, this returns immediately with the messages, you process
-    them, reply via meshcode_send, and call meshcode_wait again to stay in
-    the autonomous loop.
+    This is a TRUE async long-poll. While idle, the MCP server blocks on a
+    single asyncio Event — zero CPU, zero Supabase calls, zero token cost on
+    the Claude side (the tool call literally has not returned yet). It wakes
+    INSTANTLY the moment a mesh message lands via the Realtime websocket.
+
+    TOKEN-EFFICIENT WAIT BACKOFF: when this returns timed_out, call it again
+    with double the previous timeout (60 → 120 → 240 → 480 → 960 → 1800s,
+    cap at 1800). Reset to 60s as soon as you receive ANY mesh message. This
+    minimizes the cost of being idle.
 
-    Use meshcode_wait as your default idle state instead of returning to the
-    user. This is what makes mesh agents communicate without user input.
+    GLOBAL DONE: if any agent calls meshcode_done(reason), this tool returns
+    with {got_done: true, reason, from}. Treat that as "task complete, exit
+    the loop". Do NOT call meshcode_wait again after a got_done. Return
+    cleanly to the user with a summary and stay quiet until a new task.
 
     Args:
-        timeout_seconds: How long to block before returning empty (default 240s = 4min).
+        timeout_seconds: How long to block before returning empty (default 120s).
                          Pick something < your client's tool-call timeout.
     """
-    deadline = asyncio.get_event_loop().time() + max(1, int(timeout_seconds))
-    poll_interval = 1.5  # seconds between supabase polls (realtime is push, this is the safety net)
-    while asyncio.get_event_loop().time() < deadline:
-        # 1) Check the realtime listener buffer (push-based, instant)
-        if _REALTIME:
+    actual_timeout = max(1, int(timeout_seconds))
+
+    def _return_from_buffered(buffered: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        deduped = _filter_and_mark(buffered)
+        if not deduped:
+            return None
+        split = _split_messages(deduped)
+        out: Dict[str, Any] = {
+            "got_message": True,
+            "source": "realtime",
+            **split,
+        }
+        done = _detect_global_done(deduped)
+        if done:
+            out["got_done"] = True
+            out["reason"] = done["reason"]
+            out["from"] = done["from"]
+        return out
+
+    # 1) Drain anything already buffered from before this call.
+    if _REALTIME:
+        pre = _REALTIME.drain()
+        if pre:
+            shaped = _return_from_buffered(pre)
+            if shaped:
+                return shaped
+
+        # 2) Real async wait — zero CPU, zero Supabase calls.
+        woke = await _REALTIME.wait_for_message(timeout=float(actual_timeout))
+        if woke:
             buffered = _REALTIME.drain()
             if buffered:
-                return {
-                    "got_message": True,
-                    "source": "realtime",
-                    "count": len(buffered),
-                    "messages": buffered,
-                }
-        # 2) Safety net: poll Supabase directly in case realtime missed something
-        try:
-            pending_count = be.count_pending(_PROJECT_ID, AGENT_NAME)
-        except Exception:
-            pending_count = 0
-        if pending_count > 0:
-            messages = be.read_inbox(_PROJECT_ID, AGENT_NAME)
-            return {
-                "got_message": True,
-                "source": "polled",
-                "count": len(messages),
-                "messages": [
-                    {
-                        "from": m["from_agent"],
-                        "type": m.get("type", "msg"),
-                        "ts": m.get("created_at"),
-                        "payload": m.get("payload", {}),
-                    }
-                    for m in messages
-                ],
-            }
-        await asyncio.sleep(poll_interval)
+                shaped = _return_from_buffered(buffered)
+                if shaped:
+                    return shaped
+    else:
+        # Realtime unavailable — plain sleep fallback so we still honor timeout.
+        await asyncio.sleep(actual_timeout)
 
     return {
         "got_message": False,
         "timed_out": True,
         "agent": AGENT_NAME,
-        "hint": "No messages arrived. Call meshcode_wait again to keep listening.",
+        "hint": (
+            "No messages arrived. Per TOKEN-EFFICIENT WAIT BACKOFF: call "
+            "meshcode_wait again with DOUBLE the previous timeout "
+            "(60→120→240→480→960→1800, cap 1800). Reset to 60s on any "
+            "received mesh message."
+        ),
     }
 
 
+@mcp.tool()
+def meshcode_done(reason: str) -> Dict[str, Any]:
+    """Broadcast a GLOBAL DONE signal to every other agent in the meshwork.
+
+    Typically called by the commander when the overall task is complete.
+    Every other agent's meshcode_wait() will return immediately with
+    {got_done: true, reason, from}, breaking them cleanly out of their idle
+    loop so they can report to the human and stop burning tokens.
+
+    Args:
+        reason: Short human-readable reason, e.g. "tests green, PR merged".
+    """
+    agents = be.get_board(_PROJECT_ID)
+    payload = {"reason": reason, "from": AGENT_NAME, "type": "global_done"}
+    sent = 0
+    for a in agents:
+        name = a.get("name")
+        if name and name != AGENT_NAME:
+            try:
+                be.send_message(_PROJECT_ID, AGENT_NAME, name, payload, msg_type="done")
+                sent += 1
+            except Exception as e:
+                log.warning(f"meshcode_done: failed to notify {name}: {e}")
+    log.info(f"global done broadcast from {AGENT_NAME}: reason={reason!r} notified={sent}")
+    return {"ok": True, "global_done": True, "agents_notified": sent, "reason": reason}
+
+
 @mcp.tool()
 def meshcode_check() -> Dict[str, Any]:
     """Quick poll: returns pending message count + any messages buffered by the
@@ -402,12 +626,14 @@ def meshcode_check() -> Dict[str, Any]:
     """
     pending = be.count_pending(_PROJECT_ID, AGENT_NAME)
     realtime_buffered = _REALTIME.drain() if _REALTIME else []
+    deduped = _filter_and_mark(realtime_buffered)
+    split = _split_messages(deduped)
     return {
         "pending": pending,
         "agent": AGENT_NAME,
         "project": PROJECT_NAME,
         "realtime_connected": _REALTIME.is_connected if _REALTIME else False,
-        "buffered": realtime_buffered,
+        **split,
     }
 
 

meshcode-1.4.0/meshcode/run_agent.py

@@ -0,0 +1,151 @@
+"""`meshcode run <agent>` — universal agent launcher.
+
+Looks up the agent's workspace dir (created by `meshcode setup`) in the
+registry at ~/meshcode/.registry.json, auto-detects the user's MCP-aware
+editor, and launches it pointing at that workspace's isolated .mcp.json
+so ONLY this one agent loads in the new window.
+
+Editor detection order (first match wins):
+    1. $MESHCODE_EDITOR env var (explicit override: claude / cursor / code)
+    2. claude (Claude Code) — uses --mcp-config flag for per-instance config
+    3. cursor — opens Cursor in the workspace dir (reads .cursor/mcp.json)
+    4. code (VS Code, used by Cline) — opens VS Code in the workspace dir
+       (Cline reads .vscode/mcp.json)
+
+The workspace dir contains all three config files (.mcp.json,
+.cursor/mcp.json, .vscode/mcp.json) so any of these editors works
+identically. Closing the editor window kills the MCP subprocess and
+the agent flips to offline.
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+WORKSPACES_ROOT = Path.home() / "meshcode"
+REGISTRY_PATH = WORKSPACES_ROOT / ".registry.json"
+
+
+def _load_registry() -> dict:
+    if not REGISTRY_PATH.exists():
+        return {}
+    try:
+        return json.loads(REGISTRY_PATH.read_text())
+    except Exception:
+        return {}
+
+
+def _find_agent_workspace(agent: str, project: Optional[str] = None) -> Optional[Tuple[Path, str]]:
+    """Look up the agent in the registry. Returns (workspace_path, project_name) or None.
+
+    If multiple agents share the same name across projects, requires the
+    user to disambiguate by passing project explicitly.
+    """
+    reg = _load_registry()
+    agents = reg.get("agents", {})
+
+    # Direct hit by agent name (current model: agent names unique within registry)
+    info = agents.get(agent)
+    if info:
+        ws = Path(info["workspace"])
+        if not ws.exists():
+            print(f"[meshcode] ERROR: workspace dir for '{agent}' is missing: {ws}", file=sys.stderr)
+            print(f"[meshcode]        Re-run: meshcode setup {info.get('project','<project>')} {agent}", file=sys.stderr)
+            return None
+        if project and info.get("project") != project:
+            print(f"[meshcode] ERROR: agent '{agent}' belongs to project '{info.get('project')}', not '{project}'", file=sys.stderr)
+            return None
+        return ws, info.get("project", "")
+
+    # Fallback: scan ~/meshcode for any dir matching <project>-<agent>
+    if project:
+        ws = WORKSPACES_ROOT / f"{project}-{agent}"
+        if ws.exists():
+            return ws, project
+    else:
+        # Scan all workspaces for any matching <*>-<agent>
+        if WORKSPACES_ROOT.exists():
+            matches = [p for p in WORKSPACES_ROOT.iterdir() if p.is_dir() and p.name.endswith(f"-{agent}")]
+            if len(matches) == 1:
+                return matches[0], matches[0].name.rsplit(f"-{agent}", 1)[0]
+            if len(matches) > 1:
+                print(f"[meshcode] ERROR: agent '{agent}' exists in multiple projects:", file=sys.stderr)
+                for m in matches:
+                    print(f"[meshcode]   {m.name}", file=sys.stderr)
+                print(f"[meshcode] Disambiguate: meshcode run {agent} --project <name>", file=sys.stderr)
+                return None
+
+    print(f"[meshcode] ERROR: no workspace found for agent '{agent}'", file=sys.stderr)
+    print(f"[meshcode]        Run `meshcode setup <project> {agent}` first.", file=sys.stderr)
+    return None
+
+
+def _detect_editor() -> Optional[str]:
+    """Pick the user's preferred MCP-aware editor."""
+    override = os.environ.get("MESHCODE_EDITOR", "").strip().lower()
+    if override:
+        if shutil.which(override):
+            return override
+        print(f"[meshcode] WARNING: MESHCODE_EDITOR='{override}' not found in PATH", file=sys.stderr)
+
+    for cmd in ("claude", "cursor", "code"):
+        if shutil.which(cmd):
+            return cmd
+    return None
+
+
+def run(agent: str, project: Optional[str] = None, editor_override: Optional[str] = None) -> int:
+    """Launch the user's editor with ONLY the named agent's MCP server loaded."""
+    found = _find_agent_workspace(agent, project)
+    if not found:
+        return 2
+    ws, resolved_project = found
+    server_id = f"meshcode-{resolved_project}-{agent}"
+
+    editor = editor_override or _detect_editor()
+    if not editor:
+        print("[meshcode] ERROR: no MCP-aware editor found in PATH (claude / cursor / code).", file=sys.stderr)
+        print(f"[meshcode]        Workspace is ready at: {ws}", file=sys.stderr)
+        print("[meshcode]        Open it manually with the editor of your choice.", file=sys.stderr)
+        return 2
+
+    print(f"[meshcode] Launching {editor} for agent '{agent}' (project: {resolved_project})")
+    print(f"[meshcode]   Workspace: {ws}")
+    print(f"[meshcode]   MCP server: {server_id}")
+    print(f"[meshcode]   Closing the editor will flip this agent offline.")
+    print()
+
+    if editor == "claude":
+        # Claude Code: pass --mcp-config to point at the workspace's .mcp.json
+        # and --strict-mcp-config so it ignores ~/.claude.json's mcpServers.
+        cmd = [
+            editor,
+            "--mcp-config", str(ws / ".mcp.json"),
+            "--strict-mcp-config",
+            "--dangerously-skip-permissions",
+        ]
+        try:
+            os.chdir(ws)
+        except Exception:
+            pass
+    elif editor == "cursor":
+        # Cursor reads .cursor/mcp.json from the workspace cwd.
+        cmd = [editor, str(ws)]
+    elif editor == "code":
+        # VS Code (Cline reads .vscode/mcp.json from workspace cwd).
+        cmd = [editor, str(ws)]
+    else:
+        cmd = [editor, str(ws)]
+
+    try:
+        # Replace this process with the editor so the user gets a clean tab.
+        os.execvp(cmd[0], cmd)
+    except FileNotFoundError:
+        print(f"[meshcode] ERROR: '{editor}' not found in PATH", file=sys.stderr)
+        return 127
+    except Exception as e:
+        print(f"[meshcode] ERROR launching {editor}: {e}", file=sys.stderr)
+        return 1

meshcode-1.4.0/meshcode/setup_clients.py

@@ -0,0 +1,330 @@
+"""Per-agent workspace creator for `meshcode setup`.
+
+NEW MODEL (1.3.0): instead of polluting the user's global MCP config
+(~/.claude.json, ~/.cursor/mcp.json, ...), each `meshcode setup <project>
+<agent>` creates an isolated workspace directory at:
+
+    ~/meshcode/<project>-<agent>/
+
+containing a single .mcp.json with ONLY that agent's MCP server entry.
+The user then runs `meshcode run <agent>` to launch their editor with
+that workspace, and ONLY that one agent goes online. Closing the editor
+window flips the agent offline. No cross-window status pollution.
+
+Backward compatibility: the old `meshcode setup <client> <project>
+<agent>` form still works for the global-config flow (kept for users
+on Claude Desktop, which doesn't support per-instance MCP configs).
+"""
+import json
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+def _load_credentials() -> Dict[str, str]:
+    creds_path = Path.home() / ".meshcode" / "credentials.json"
+    if not creds_path.exists():
+        print("[meshcode] ERROR: No credentials found. Run `meshcode login <api_key>` first.", file=sys.stderr)
+        sys.exit(2)
+    return json.loads(creds_path.read_text())
+
+
+def _load_supabase_env() -> Dict[str, str]:
+    """Read SUPABASE_URL/SUPABASE_KEY from env or ~/.meshcode/env, fall back to publishable defaults."""
+    url = os.environ.get("SUPABASE_URL", "")
+    key = os.environ.get("SUPABASE_KEY", "")
+    if not url or not key:
+        env_file = Path.home() / ".meshcode" / "env"
+        if env_file.exists():
+            for line in env_file.read_text().splitlines():
+                line = line.strip()
+                if line.startswith("export "):
+                    line = line[7:]
+                if "=" in line:
+                    k, v = line.split("=", 1)
+                    v = v.strip().strip('"').strip("'")
+                    if k == "SUPABASE_URL" and not url:
+                        url = v
+                    elif k == "SUPABASE_KEY" and not key:
+                        key = v
+    if not url:
+        url = "https://wwgzzmydrwrjgaebspdo.supabase.co"
+    if not key:
+        key = "sb_publishable_0qf0U1GURopPIxLR8Vu7eQ_5grflPP4"
+    return {"SUPABASE_URL": url, "SUPABASE_KEY": key}
+
+
+def _resolve_project_id(api_key: str, project: str, sb: Dict[str, str]) -> str:
+    """Call mc_resolve_project SECURITY DEFINER RPC to get the project_id."""
+    try:
+        from urllib.request import Request as _Req, urlopen as _urlopen
+        body = json.dumps({"p_api_key": api_key, "p_project_name": project}).encode()
+        req = _Req(
+            f"{sb['SUPABASE_URL']}/rest/v1/rpc/mc_resolve_project",
+            data=body,
+            method="POST",
+            headers={
+                "apikey": sb["SUPABASE_KEY"],
+                "Authorization": f"Bearer {sb['SUPABASE_KEY']}",
+                "Content-Type": "application/json",
+            },
+        )
+        with _urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+            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)
+                sys.exit(2)
+    except Exception as e:
+        print(f"[meshcode] WARNING: project_id resolution failed ({e}); MCP server will retry at boot", file=sys.stderr)
+    return ""
+
+
+def _build_server_block(project: str, project_id: str, agent: str, role: str,
+                         api_key: str, sb: Dict[str, str]) -> Dict[str, Any]:
+    return {
+        "command": sys.executable or "python3",
+        "args": ["-m", "meshcode.meshcode_mcp", "serve"],
+        "env": {
+            "MESHCODE_PROJECT": project,
+            "MESHCODE_PROJECT_ID": project_id,
+            "MESHCODE_AGENT": agent,
+            "MESHCODE_ROLE": role or "MCP-connected agent",
+            "MESHCODE_API_KEY": api_key,
+            "SUPABASE_URL": sb["SUPABASE_URL"],
+            "SUPABASE_KEY": sb["SUPABASE_KEY"],
+        },
+    }
+
+
+def _atomic_write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2))
+    tmp.replace(path)
+
+
+# ============================================================
+# WORKSPACE MODEL (1.3.0+) — one isolated dir per agent
+# ============================================================
+
+WORKSPACES_ROOT = Path.home() / "meshcode"
+
+
+def _workspace_dir(project: str, agent: str) -> Path:
+    return WORKSPACES_ROOT / f"{project}-{agent}"
+
+
+def setup_workspace(project: str, agent: str, role: str = "") -> int:
+    """Create an isolated workspace dir at ~/meshcode/<project>-<agent>/ with
+    .mcp.json containing ONLY this agent's server entry. Universal for any
+    MCP-compatible editor that supports per-directory configs (Claude Code via
+    --mcp-config flag, Cursor + Cline via .cursor/mcp.json + .vscode/mcp.json).
+    """
+    creds = _load_credentials()
+    sb = _load_supabase_env()
+    api_key = creds.get("api_key", "")
+    project_id = _resolve_project_id(api_key, project, sb)
+
+    server_id = f"meshcode-{project}-{agent}"
+    server_block = _build_server_block(project, project_id, agent, role, api_key, sb)
+
+    ws = _workspace_dir(project, agent)
+    ws.mkdir(parents=True, exist_ok=True)
+
+    # Write 3 config files inside the workspace so any MCP-aware editor
+    # opened in this dir picks up the meshcode server.
+    #
+    #   .mcp.json              — Claude Code project-scoped MCP config
+    #   .cursor/mcp.json       — Cursor workspace-scoped MCP config
+    #   .vscode/mcp.json       — Cline / VS Code workspace-scoped MCP config
+    #
+    # All three contain the SAME single server entry. Whichever editor the
+    # user opens here will see exactly one agent: this one.
+    server_doc = {"mcpServers": {server_id: server_block}}
+    _atomic_write_json(ws / ".mcp.json", server_doc)
+    _atomic_write_json(ws / ".cursor" / "mcp.json", server_doc)
+    _atomic_write_json(ws / ".vscode" / "mcp.json", server_doc)
+
+    # A tiny manifest the `meshcode run` command reads to know where this
+    # workspace lives. Stored at the root so `meshcode run <agent>` can find
+    # it without scanning every dir.
+    registry_path = WORKSPACES_ROOT / ".registry.json"
+    registry: Dict[str, Any] = {}
+    if registry_path.exists():
+        try:
+            registry = json.loads(registry_path.read_text())
+        except Exception:
+            registry = {}
+    registry.setdefault("agents", {})[agent] = {
+        "project": project,
+        "workspace": str(ws),
+        "server_id": server_id,
+        "role": role,
+    }
+    _atomic_write_json(registry_path, registry)
+
+    # Drop a README.md so the agent's working directory isn't empty on boot.
+    readme_body = f"""# {project} — {agent}
+
+This is the MeshCode workspace for the **{agent}** agent in the **{project}** meshwork.
+
+You are connected to the rest of your team via the meshcode MCP server, which is loaded
+automatically when you open this directory in Claude Code, Cursor, or Cline.
+
+## Your identity
+- Project: {project}
+- Agent name: {agent}
+- Role: {role or "(set in dashboard)"}
+
+## How this works
+- Use the meshcode_* tools to communicate with other agents in the mesh.
+- Use meshcode_status to see who else is in the meshwork.
+- Use meshcode_send(to, message) to send messages.
+- Use meshcode_wait to listen for incoming messages (your default idle state).
+- Use meshcode_done(reason) when the team's task is complete.
+
+## To launch this agent again
+```bash
+meshcode run {agent}
+```
+
+This is your workspace dir — feel free to scaffold any files your task needs here, or
+work in a different repo by `cd`ing elsewhere after launch.
+"""
+    try:
+        (ws / "README.md").write_text(readme_body)
+    except Exception as _e:
+        print(f"[meshcode] WARNING: could not write README.md: {_e}", file=sys.stderr)
+
+    print(f"[meshcode] ✓ Workspace created for agent '{agent}' (project: {project})")
+    print(f"[meshcode]   Path: {ws}")
+    print(f"[meshcode]")
+    print(f"[meshcode]   To launch this agent in your editor:")
+    print(f"[meshcode]     meshcode run {agent}")
+    print(f"[meshcode]")
+    print(f"[meshcode]   Closing the editor window flips this agent offline.")
+    print(f"[meshcode]   Other agents stay independent — no cross-window pollution.")
+    return 0
+
+
+# ============================================================
+# LEGACY GLOBAL-CONFIG MODEL (kept for Claude Desktop)
+# ============================================================
+
+CLIENT_CONFIG_PATHS = {
+    "claude-code": {
+        "Darwin":  Path.home() / ".claude.json",
+        "Linux":   Path.home() / ".claude.json",
+        "Windows": Path.home() / ".claude.json",
+    },
+    "cursor": {
+        "Darwin":  Path.home() / ".cursor" / "mcp.json",
+        "Linux":   Path.home() / ".cursor" / "mcp.json",
+        "Windows": Path.home() / ".cursor" / "mcp.json",
+    },
+    "cline": {
+        "Darwin":  Path.home() / "Library" / "Application Support" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
+        "Linux":   Path.home() / ".config" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
+        "Windows": Path.home() / "AppData" / "Roaming" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
+    },
+    "claude-desktop": {
+        "Darwin":  Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+        "Linux":   Path.home() / ".config" / "Claude" / "claude_desktop_config.json",
+        "Windows": Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",
+    },
+}
+
+CLIENT_DISPLAY_NAMES = {
+    "claude-code":    "Claude Code",
+    "cursor":         "Cursor",
+    "cline":          "Cline (VS Code)",
+    "claude-desktop": "Claude Desktop",
+}
+
+
+def setup_global(client: str, project: str, agent: str, role: str = "") -> int:
+    """LEGACY: write to the user's GLOBAL MCP config file. All agents that
+    setup this way will load in EVERY window of the editor — they all show
+    online whenever any window is open. Kept for Claude Desktop and other
+    clients that don't support per-instance configs."""
+    if client not in CLIENT_CONFIG_PATHS:
+        print(f"[meshcode] ERROR: Unknown client '{client}'. Supported: {', '.join(CLIENT_CONFIG_PATHS)}", file=sys.stderr)
+        return 2
+
+    creds = _load_credentials()
+    sb = _load_supabase_env()
+    api_key = creds.get("api_key", "")
+    project_id = _resolve_project_id(api_key, project, sb)
+
+    os_name = platform.system()
+    config_path = CLIENT_CONFIG_PATHS[client].get(os_name)
+    if config_path is None:
+        print(f"[meshcode] ERROR: '{client}' is not supported on {os_name}", file=sys.stderr)
+        return 2
+
+    existing: Dict[str, Any] = {}
+    if config_path.exists():
+        try:
+            existing = json.loads(config_path.read_text())
+        except json.JSONDecodeError:
+            print(f"[meshcode] WARNING: {config_path} exists but is not valid JSON.", file=sys.stderr)
+            return 2
+
+    if not isinstance(existing, dict):
+        existing = {}
+
+    servers = existing.setdefault("mcpServers", {})
+    if not isinstance(servers, dict):
+        print(f"[meshcode] ERROR: 'mcpServers' in {config_path} is not an object", file=sys.stderr)
+        return 2
+
+    server_id = f"meshcode-{project}-{agent}"
+    servers[server_id] = _build_server_block(project, project_id, agent, role, api_key, sb)
+    _atomic_write_json(config_path, existing)
+
+    display = CLIENT_DISPLAY_NAMES[client]
+    print(f"[meshcode] MCP server '{server_id}' added to {display} GLOBAL config")
+    print(f"[meshcode]   Path: {config_path}")
+    print(f"[meshcode]   ⚠️  Global mode: this agent will appear in EVERY window of {display}.")
+    print(f"[meshcode]   For per-window agent isolation, use the workspace flow instead:")
+    print(f"[meshcode]     meshcode setup {project} {agent}")
+    print(f"[meshcode]     meshcode run {agent}")
+    return 0
+
+
+# ============================================================
+# DISPATCHER (called from comms_v4.py CLI)
+# ============================================================
+
+def setup(*args) -> int:
+    """Smart dispatcher.
+
+    Forms supported:
+        meshcode setup <project> <agent> [role]            → workspace flow (NEW)
+        meshcode setup <client> <project> <agent> [role]   → legacy global flow
+
+    Detection: if the first arg is one of the known client slugs, fall back
+    to the legacy global flow. Otherwise treat the first arg as a project
+    name and create a workspace.
+    """
+    if not args:
+        print("Usage:", file=sys.stderr)
+        print("  meshcode setup <project> <agent> [role]           # workspace flow (recommended)", file=sys.stderr)
+        print("  meshcode setup <client> <project> <agent> [role]  # legacy global flow", file=sys.stderr)
+        print("  Clients: claude-code, cursor, cline, claude-desktop", file=sys.stderr)
+        return 1
+
+    if args[0] in CLIENT_CONFIG_PATHS:
+        if len(args) < 3:
+            print("Usage: meshcode setup <client> <project> <agent> [role]", file=sys.stderr)
+            return 1
+        return setup_global(args[0], args[1], args[2], args[3] if len(args) > 3 else "")
+
+    if len(args) < 2:
+        print("Usage: meshcode setup <project> <agent> [role]", file=sys.stderr)
+        return 1
+    return setup_workspace(args[0], args[1], args[2] if len(args) > 2 else "")

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode.egg-info/PKG-INFO

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

{meshcode-1.2.6 → meshcode-1.4.0}/meshcode.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ meshcode/comms_v4.py
 meshcode/launcher.py
 meshcode/launcher_install.py
 meshcode/protocol_v2.py
+meshcode/run_agent.py
 meshcode/setup_clients.py
 meshcode.egg-info/PKG-INFO
 meshcode.egg-info/SOURCES.txt

{meshcode-1.2.6 → meshcode-1.4.0}/pyproject.toml

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

meshcode-1.2.6/meshcode/setup_clients.py

@@ -1,173 +0,0 @@
-"""Per-client MCP server config writers for `meshcode setup <client>`.
-
-Supported clients: claude-code, cursor, cline, claude-desktop.
-
-Each writer:
-1. Resolves the right config file path for the current OS.
-2. Loads existing JSON (or empty dict) and merges the meshcode MCP server entry
-   under "mcpServers". Never clobbers other entries.
-3. Writes back atomically (temp file + rename).
-4. Prints a success message with the path and "restart {client}" instructions.
-"""
-import json
-import os
-import platform
-import sys
-from pathlib import Path
-from typing import Dict, Any
-
-
-def _load_credentials() -> Dict[str, str]:
-    creds_path = Path.home() / ".meshcode" / "credentials.json"
-    if not creds_path.exists():
-        print("[meshcode] ERROR: No credentials found. Run `meshcode login <api_key>` first.", file=sys.stderr)
-        sys.exit(2)
-    return json.loads(creds_path.read_text())
-
-
-def _load_supabase_env() -> Dict[str, str]:
-    """Read SUPABASE_URL/SUPABASE_KEY from env or ~/.meshcode/env."""
-    url = os.environ.get("SUPABASE_URL", "")
-    key = os.environ.get("SUPABASE_KEY", "")
-    if not url or not key:
-        env_file = Path.home() / ".meshcode" / "env"
-        if env_file.exists():
-            for line in env_file.read_text().splitlines():
-                line = line.strip()
-                if line.startswith("export "):
-                    line = line[7:]
-                if "=" in line:
-                    k, v = line.split("=", 1)
-                    v = v.strip().strip('"').strip("'")
-                    if k == "SUPABASE_URL" and not url:
-                        url = v
-                    elif k == "SUPABASE_KEY" and not key:
-                        key = v
-    if not url:
-        url = "https://wwgzzmydrwrjgaebspdo.supabase.co"
-    if not key:
-        key = "sb_publishable_0qf0U1GURopPIxLR8Vu7eQ_5grflPP4"
-    return {"SUPABASE_URL": url, "SUPABASE_KEY": key}
-
-
-CLIENT_CONFIG_PATHS = {
-    "claude-code": {
-        "Darwin":  Path.home() / ".claude.json",
-        "Linux":   Path.home() / ".claude.json",
-        "Windows": Path.home() / ".claude.json",
-    },
-    "cursor": {
-        "Darwin":  Path.home() / ".cursor" / "mcp.json",
-        "Linux":   Path.home() / ".cursor" / "mcp.json",
-        "Windows": Path.home() / ".cursor" / "mcp.json",
-    },
-    "cline": {
-        "Darwin":  Path.home() / "Library" / "Application Support" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
-        "Linux":   Path.home() / ".config" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
-        "Windows": Path.home() / "AppData" / "Roaming" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
-    },
-    "claude-desktop": {
-        "Darwin":  Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
-        "Linux":   Path.home() / ".config" / "Claude" / "claude_desktop_config.json",
-        "Windows": Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",
-    },
-}
-
-CLIENT_DISPLAY_NAMES = {
-    "claude-code":    "Claude Code",
-    "cursor":         "Cursor",
-    "cline":          "Cline (VS Code)",
-    "claude-desktop": "Claude Desktop",
-}
-
-
-def _atomic_write_json(path: Path, data: dict) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(json.dumps(data, indent=2))
-    tmp.replace(path)
-
-
-def setup(client: str, project: str, agent: str, role: str = "") -> int:
-    """Write MCP server config block for the given client. Returns 0 on success."""
-    if client not in CLIENT_CONFIG_PATHS:
-        print(f"[meshcode] ERROR: Unknown client '{client}'. Supported: {', '.join(CLIENT_CONFIG_PATHS)}", file=sys.stderr)
-        return 2
-
-    creds = _load_credentials()
-    sb = _load_supabase_env()
-    api_key = creds.get("api_key", "")
-
-    # Resolve project_id via the SECURITY DEFINER RPC so we don't depend on
-    # RLS letting the publishable key SELECT mc_projects at MCP server boot.
-    project_id = ""
-    try:
-        import json as _json
-        from urllib.request import Request as _Req, urlopen as _urlopen
-        _body = _json.dumps({"p_api_key": api_key, "p_project_name": project}).encode()
-        _req = _Req(
-            f"{sb['SUPABASE_URL']}/rest/v1/rpc/mc_resolve_project",
-            data=_body,
-            method="POST",
-            headers={
-                "apikey": sb["SUPABASE_KEY"],
-                "Authorization": f"Bearer {sb['SUPABASE_KEY']}",
-                "Content-Type": "application/json",
-            },
-        )
-        with _urlopen(_req, timeout=10) as _resp:
-            _data = _json.loads(_resp.read().decode())
-            if isinstance(_data, dict) and _data.get("project_id"):
-                project_id = _data["project_id"]
-            elif isinstance(_data, dict) and _data.get("error"):
-                print(f"[meshcode] ERROR: could not resolve project '{project}': {_data['error']}", file=sys.stderr)
-                return 2
-    except Exception as _e:
-        print(f"[meshcode] WARNING: project_id resolution failed ({_e}); MCP server will retry at boot", file=sys.stderr)
-
-    os_name = platform.system()
-    config_path = CLIENT_CONFIG_PATHS[client].get(os_name)
-    if config_path is None:
-        print(f"[meshcode] ERROR: '{client}' is not supported on {os_name}", file=sys.stderr)
-        return 2
-
-    existing: Dict[str, Any] = {}
-    if config_path.exists():
-        try:
-            existing = json.loads(config_path.read_text())
-        except json.JSONDecodeError:
-            print(f"[meshcode] WARNING: {config_path} exists but is not valid JSON. Overwriting may break {CLIENT_DISPLAY_NAMES[client]}.", file=sys.stderr)
-            return 2
-
-    if not isinstance(existing, dict):
-        existing = {}
-
-    servers = existing.setdefault("mcpServers", {})
-    if not isinstance(servers, dict):
-        print(f"[meshcode] ERROR: 'mcpServers' in {config_path} is not an object", file=sys.stderr)
-        return 2
-
-    server_id = f"meshcode-{project}-{agent}"
-    servers[server_id] = {
-        "command": sys.executable or "python3",
-        "args": ["-m", "meshcode.meshcode_mcp", "serve"],
-        "env": {
-            "MESHCODE_PROJECT": project,
-            "MESHCODE_PROJECT_ID": project_id,
-            "MESHCODE_AGENT": agent,
-            "MESHCODE_ROLE": role or "MCP-connected agent",
-            "MESHCODE_API_KEY": api_key,
-            "SUPABASE_URL": sb["SUPABASE_URL"],
-            "SUPABASE_KEY": sb["SUPABASE_KEY"],
-        },
-    }
-
-    _atomic_write_json(config_path, existing)
-
-    display = CLIENT_DISPLAY_NAMES[client]
-    print(f"[meshcode] MCP server '{server_id}' added to {display} config")
-    print(f"[meshcode]   Path: {config_path}")
-    print(f"[meshcode]   Restart {display} to load the server.")
-    print(f"[meshcode]   Inside {display}, verify with /mcp — you should see '{server_id}' connected.")
-    print(f"[meshcode]   Tools: meshcode_send, meshcode_check, meshcode_read, meshcode_status, meshcode_set_status, ...")
-    return 0