meshcode 1.3.0__tar.gz → 1.4.0__tar.gz

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

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

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

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

{meshcode-1.3.0 → 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.3.0 → 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
@@ -111,6 +178,54 @@ 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
+
+
 # ============================================================
 # Agent identity from Supabase profile (for system instructions)
 # ============================================================
@@ -180,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.
@@ -213,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
@@ -282,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}")
 
 
 # ============================================================
@@ -311,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")
 
 
@@ -339,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
@@ -427,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.3.0 → meshcode-1.4.0}/meshcode/setup_clients.py

@@ -167,6 +167,39 @@ def setup_workspace(project: str, agent: str, role: str = "") -> int:
     }
     _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]")

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

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

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

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