meshcode 2.0.0__tar.gz → 2.0.1__tar.gz

{meshcode-2.0.0 → meshcode-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.0.0
+Version: 2.0.1
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -158,6 +158,29 @@ meshcode revoke-member my-project <user> # kick a member instantly
 
 ---
 
+## Agent account management
+
+Your AI agents can manage your MeshCode account from inside the mesh. Just tell your agent what you need:
+
+- **"Create a backend agent"** → agent calls `meshcode_create_meshwork` + `meshcode_add_agent`
+- **"Change the frontend role to UI designer"** → agent calls `meshcode_edit_agent`
+- **"Give the backend agent a note about our conventions"** → agent calls `meshcode_edit_memory`
+
+Available MCP tools for agents:
+
+| Tool | What it does |
+|------|-------------|
+| `meshcode_create_meshwork(name)` | Create a new meshwork |
+| `meshcode_add_agent(name, role)` | Add an agent to the current meshwork |
+| `meshcode_edit_agent(name, role?, launch_prompt?)` | Update agent role or system prompt |
+| `meshcode_edit_memory(agent_name, key, value)` | Edit another agent's persistent memory |
+| `meshcode_scratchpad_set(key, value)` | Write to shared meshwork memory |
+| `meshcode_link(target_meshwork)` | Link two meshworks for cross-mesh communication |
+
+The agent will always tell you what CLI command to run next (e.g., "Open a new terminal and run `meshcode run backend`").
+
+---
+
 ## Editor support
 
 | Editor | Auto-detected? | Config file written |

{meshcode-2.0.0 → meshcode-2.0.1}/README.md

@@ -133,6 +133,29 @@ meshcode revoke-member my-project <user> # kick a member instantly
 
 ---
 
+## Agent account management
+
+Your AI agents can manage your MeshCode account from inside the mesh. Just tell your agent what you need:
+
+- **"Create a backend agent"** → agent calls `meshcode_create_meshwork` + `meshcode_add_agent`
+- **"Change the frontend role to UI designer"** → agent calls `meshcode_edit_agent`
+- **"Give the backend agent a note about our conventions"** → agent calls `meshcode_edit_memory`
+
+Available MCP tools for agents:
+
+| Tool | What it does |
+|------|-------------|
+| `meshcode_create_meshwork(name)` | Create a new meshwork |
+| `meshcode_add_agent(name, role)` | Add an agent to the current meshwork |
+| `meshcode_edit_agent(name, role?, launch_prompt?)` | Update agent role or system prompt |
+| `meshcode_edit_memory(agent_name, key, value)` | Edit another agent's persistent memory |
+| `meshcode_scratchpad_set(key, value)` | Write to shared meshwork memory |
+| `meshcode_link(target_meshwork)` | Link two meshworks for cross-mesh communication |
+
+The agent will always tell you what CLI command to run next (e.g., "Open a new terminal and run `meshcode run backend`").
+
+---
+
 ## Editor support
 
 | Editor | Auto-detected? | Config file written |

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode/__init__.py

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

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode/comms_v4.py

@@ -1503,11 +1503,12 @@ def connect(project, name, hook_target="claude", role=""):
     comms_path = str(Path(__file__).resolve())
 
     if hook_target == "claude":
-        # Delegate to the universal setup_clients writer. `meshcode connect` is
-        # now a backwards-compat alias for `meshcode setup claude-code`.
+        # Use workspace flow (NOT global) to avoid polluting ~/.claude.json.
+        # Global configs cause all Claude Code windows to load all agents,
+        # triggering lease conflicts and "x failed" errors.
         import importlib
-        _setup_client = importlib.import_module("meshcode.setup_clients").setup
-        _setup_client("claude-code", project, name, actual_role)
+        _setup_ws = importlib.import_module("meshcode.setup_clients").setup_workspace
+        _setup_ws(project, name, actual_role)
 
     elif hook_target == "codex":
         config_path = Path.cwd() / ".meshcode.json"

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode/meshcode_mcp/server.py

@@ -240,30 +240,31 @@ if isinstance(_register_result, dict) and _register_result.get("error"):
 # 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 = _get_api_key()
-    if not api_key:
-        # Last-resort fallback: try the direct PATCH (may be denied by RLS)
+    """Write status directly to mc_agents table for instant Realtime propagation.
+
+    Uses direct PATCH (not RPC) so Supabase Realtime fires an UPDATE event
+    immediately — the dashboard sees the change in <100ms instead of waiting
+    for the next heartbeat cycle.
+    """
+    try:
+        be.set_status(_PROJECT_ID, AGENT_NAME, status, task)
+        return True
+    except Exception:
+        # Fallback to RPC if direct PATCH fails (RLS issue)
+        api_key = _get_api_key()
+        if not api_key:
+            return False
         try:
-            be.set_status(_PROJECT_ID, AGENT_NAME, status, task)
-            return True
+            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,
+            })
+            return isinstance(r, dict) and r.get("ok", False)
         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("idle", ""):
     print(f"[meshcode-mcp] WARNING: could not flip status to idle", file=sys.stderr)
@@ -341,23 +342,67 @@ def _acquire_lease() -> bool:
     api_key = _get_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
+    import time as _time
+    for attempt in range(3):
+        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"):
+                err = str(r.get("error", ""))
+                if "already running" in err:
+                    if attempt < 2:
+                        # The old lease might be stale — wait and retry
+                        # (the 90s stale check in the RPC should clear it)
+                        print(f"[meshcode-mcp] Lease held by another instance — retrying in {2 * (attempt+1)}s...", file=sys.stderr)
+                        _time.sleep(2 * (attempt + 1))
+                        continue
+                    # Final attempt — force release the old lease and try once more
+                    print(f"[meshcode-mcp] Force-releasing stale lease...", file=sys.stderr)
+                    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": r.get("held_by", "unknown"),
+                        })
+                    except Exception:
+                        # Force clear via direct update
+                        try:
+                            be.set_status(_PROJECT_ID, AGENT_NAME, "offline", "")
+                        except Exception:
+                            pass
+                    _time.sleep(1)
+                    # One more try after force-release
+                    try:
+                        r2 = 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(r2, dict) and r2.get("ok"):
+                            print(f"[meshcode-mcp] Lease acquired after force-release.", file=sys.stderr)
+                            return True
+                    except Exception:
+                        pass
+                    print(f"[meshcode-mcp] ERROR: Could not start — agent '{AGENT_NAME}' is running in another window.", file=sys.stderr)
+                    print(f"[meshcode-mcp] Close the other window first, or use a different agent name.", file=sys.stderr)
+                    return False
+                print(f"[meshcode-mcp] lease attempt {attempt+1}: {r.get('error')}", file=sys.stderr)
+            else:
+                return True
+        except Exception as e:
+            print(f"[meshcode-mcp] lease attempt {attempt+1} failed: {e}", file=sys.stderr)
+        if attempt < 2:
+            _time.sleep(2)
+    print(f"[meshcode-mcp] WARNING: lease failed after 3 attempts — proceeding anyway", file=sys.stderr)
+    return True
 
 if not _acquire_lease():
     sys.exit(2)
@@ -418,7 +463,7 @@ def _build_instructions() -> str:
         f"\nUSER-PROVIDED ROLE PROMPT (from the dashboard):\n---\n{_LAUNCH_PROMPT}\n---\n"
         if _LAUNCH_PROMPT else ""
     )
-    return f"""You are agent "{AGENT_NAME}" in meshwork "{PROJECT_NAME}".{role_block}{launch_block}
+    base = f"""You are agent "{AGENT_NAME}" in meshwork "{PROJECT_NAME}".{role_block}{launch_block}
 
 BEHAVIOR LOOP (your default state — never exit unless told):
 1. Act on task/message → 2. meshcode_send if needed → 3. meshcode_wait()
@@ -427,6 +472,9 @@ BEHAVIOR LOOP (your default state — never exit unless told):
 5. Only break loop if: user says stop, fatal error, or "tell the human X".
 
 RULES:
+- NEVER use CLI commands (meshcode watch, meshcode read, meshcode send) in bash.
+  Use ONLY the MCP tools: meshcode_check, meshcode_read, meshcode_send, meshcode_wait.
+  CLI commands are for humans in terminal. You have MCP tools — use them.
 - Tasks > messages. Use meshcode_tasks/claim/complete for trackable work.
 - Messages <100 tokens, signal-only. Long content → create task instead.
 - No empty acks ("OK"/"Got it"). No prose padding. JSON reports only.
@@ -436,8 +484,10 @@ RULES:
 - No feedback loops: stop if >10 messages on same topic.
 
 SESSION START:
-1. meshcode_status() — see who's online
-2. Act on user task or meshcode_wait()
+1. meshcode_set_status(status="online", task="ready") — announce you're online
+2. meshcode_check() — read any messages waiting in your inbox
+3. meshcode_status() — see who's online
+4. Act on user task or meshcode_wait()
 (Memories are pre-loaded below — no need to call meshcode_recall on boot.)
 
 CROSS-MESH: meshcode_send(to="agent@meshwork") routes via active link.
@@ -459,6 +509,23 @@ what CLI command to run next (e.g. "meshcode run backend in a new terminal").
 
 Setup help → README.md or https://meshcode.io/docs
 """
+    # Inject commander protocol if this agent is a leader
+    is_leader = any(k in (_ROLE_DESCRIPTION or '').lower() + AGENT_NAME.lower() for k in ('commander', 'lead', 'orchestrat'))
+    if is_leader:
+        base += """
+COMMANDER PROTOCOL (you are the team lead):
+- ALWAYS delegate via meshcode_task_create, NEVER via long messages.
+- Tasks are the source of truth. Messages are signals only (<100 tokens).
+- Workflow: identify work → create task → signal assignee → poll progress → verify → next.
+- Poll meshcode_tasks() to track completion. Don't wait for messages.
+- Verify builds/quality before approving. Don't approve blindly.
+- Communicate changes to affected agents IMMEDIATELY after you make them.
+- Organize: break big requests into multiple tasks, assign to the right agent.
+- Keep the human informed with brief status updates at milestones.
+- You are autonomous: fix small issues yourself, delegate big ones.
+- After each sprint: consolidate learnings, update scratchpad, save to memory.
+"""
+    return base
 
 
 _INSTRUCTIONS = _build_instructions()
@@ -513,26 +580,34 @@ async def _on_new_message(msg: Dict[str, Any]) -> None:
         log.debug(f"send_resource_updated unavailable: {e}")
 
 
-async def _heartbeat_loop():
-    """Send heartbeat every 30s via HTTP. Also renews the agent lease and
-    logs when the WebSocket is disconnected (heartbeat still works via HTTP
-    so the agent stays 'online' in the DB even during WS reconnects)."""
-    _lease_counter = 0
-    while True:
+_heartbeat_stop = _threading.Event()
+
+
+def _heartbeat_thread_fn():
+    """Heartbeat in a DAEMON THREAD — independent of asyncio event loop.
+
+    This ensures heartbeats continue even when tool calls are cancelled,
+    meshcode_wait is rejected, or the asyncio loop is busy. The agent
+    stays 'online' in the dashboard as long as the MCP process is alive.
+    """
+    lease_counter = 0
+    while not _heartbeat_stop.is_set():
         try:
-            be.sb_rpc("mc_heartbeat", {"p_project_id": _PROJECT_ID, "p_agent_name": AGENT_NAME})
-            # Log WS health for diagnostics
+            be.sb_rpc("mc_heartbeat", {"p_project_id": _PROJECT_ID, "p_agent_name": AGENT_NAME, "p_version": "2.0.0"})
+            # Also ensure status is at least "idle" (not "offline") between tool calls
+            try:
+                be.set_status(_PROJECT_ID, AGENT_NAME, "idle", "")
+            except Exception:
+                pass
             if _REALTIME and not _REALTIME.is_connected:
-                log.warning("heartbeat ok (HTTP) but WebSocket is disconnected — realtime messages may be delayed")
+                log.warning("heartbeat ok (HTTP) but WebSocket disconnected")
             else:
                 log.debug(f"heartbeat ok for {AGENT_NAME}")
         except Exception as e:
             log.warning(f"heartbeat failed: {e}")
 
-        # Renew lease every ~2 minutes (every 4th heartbeat) to prevent
-        # another instance from stealing it during long sessions.
-        _lease_counter += 1
-        if _lease_counter % 4 == 0:
+        lease_counter += 1
+        if lease_counter % 4 == 0:
             try:
                 api_key = _get_api_key()
                 if api_key:
@@ -545,7 +620,7 @@ async def _heartbeat_loop():
             except Exception as e:
                 log.warning(f"lease renewal failed: {e}")
 
-        await asyncio.sleep(30)
+        _heartbeat_stop.wait(30)  # sleep but interruptible on shutdown
 
 
 @asynccontextmanager
@@ -560,17 +635,30 @@ async def lifespan(_app):
         notify_callback=_on_new_message,
     )
     await _REALTIME.start()
-    hb_task = asyncio.create_task(_heartbeat_loop())
-    log.info(f"lifespan started — Realtime + heartbeat (30s) active for {AGENT_NAME}")
+
+    # IMMEDIATE: send first heartbeat + set online status BEFORE any tool calls.
+    # Without this, the agent appears offline for up to 30s after boot.
+    for _attempt in range(3):
+        try:
+            be.sb_rpc("mc_heartbeat", {"p_project_id": _PROJECT_ID, "p_agent_name": AGENT_NAME, "p_version": "2.0.0"})
+            be.set_status(_PROJECT_ID, AGENT_NAME, "idle", "MCP session active")
+            log.info(f"[meshcode] Agent {AGENT_NAME} online — initial heartbeat sent")
+            break
+        except Exception as e:
+            log.warning(f"initial heartbeat attempt {_attempt+1} failed: {e}")
+            import time; time.sleep(2)
+
+    # Heartbeat in daemon thread — independent of asyncio event loop.
+    _heartbeat_stop.clear()
+    hb_thread = _threading.Thread(target=_heartbeat_thread_fn, daemon=True, name="meshcode-heartbeat")
+    hb_thread.start()
+    log.info(f"lifespan started — Realtime + heartbeat thread active for {AGENT_NAME}")
     try:
         yield {"realtime": _REALTIME}
     finally:
         log.info("lifespan shutdown — stopping heartbeat + realtime + releasing lease")
-        hb_task.cancel()
-        try:
-            await hb_task
-        except asyncio.CancelledError:
-            pass
+        _heartbeat_stop.set()
+        hb_thread.join(timeout=5)
         await _REALTIME.stop()
         # Flip to offline + release lease so the dashboard reflects reality
         # within seconds (not waiting for the 30s cron to notice).
@@ -786,15 +874,32 @@ def meshcode_done(reason: str) -> Dict[str, Any]:
 @mcp.tool()
 @with_working_status
 def meshcode_check(include_acks: bool = False) -> Dict[str, Any]:
-    """Non-blocking: returns pending message count + buffered messages from the
-    Realtime listener since the last check.
+    """Non-blocking: returns pending message count + any new messages.
 
-    Use this to check if there's anything new without marking messages as read.
-    Useful as the first call in a tool loop or after a long thinking phase.
+    Checks realtime buffer first, then falls back to DB if buffer is empty
+    but there are pending messages (handles messages that arrived before
+    the realtime listener connected).
     """
     pending = be.count_pending(_PROJECT_ID, AGENT_NAME)
     realtime_buffered = _REALTIME.drain() if _REALTIME else []
     deduped = _filter_and_mark(realtime_buffered)
+
+    # Fallback: if realtime buffer is empty but DB has pending messages,
+    # fetch them from the DB so they're not invisible to the agent.
+    if not deduped and pending > 0:
+        raw = be.read_inbox(_PROJECT_ID, AGENT_NAME)
+        deduped = _filter_and_mark([
+            {
+                "from": m["from_agent"],
+                "type": m.get("type", "msg"),
+                "ts": m.get("created_at"),
+                "payload": m.get("payload", {}),
+                "id": m.get("id"),
+                "parent_id": m.get("parent_msg_id"),
+            }
+            for m in raw
+        ])
+
     split = _split_messages(deduped)
     if not include_acks:
         split["acks"] = []
@@ -1271,7 +1376,6 @@ def meshcode_forget(key: str) -> Dict[str, Any]:
 
 # ----------------- RESOURCES -----------------
 
-@mcp.resource("meshcode://inbox")
 @mcp.tool()
 def meshcode_auto_wake(enabled: bool) -> Dict[str, Any]:
     """Toggle auto-wake: when enabled, if this agent receives a mesh message

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode/run_agent.py

@@ -183,8 +183,14 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         cmd = [editor, str(ws)]
 
     try:
-        # Replace this process with the editor so the user gets a clean tab.
-        os.execvp(cmd[0], cmd)
+        if sys.platform == "win32":
+            # Windows: no execvp, use subprocess and wait
+            import subprocess as _sp
+            result = _sp.run(cmd)
+            sys.exit(result.returncode)
+        else:
+            # Unix: replace this process with the editor
+            os.execvp(cmd[0], cmd)
     except FileNotFoundError:
         print(f"[meshcode] ERROR: '{editor}' not found in PATH", file=sys.stderr)
         return 127

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode/setup_clients.py

@@ -588,10 +588,18 @@ def setup(*args) -> int:
         return 1
 
     if args[0] in CLIENT_CONFIG_PATHS:
+        if args[0] == "claude-desktop":
+            # Claude Desktop needs global config — only exception
+            if len(args) < 3:
+                print("Usage: meshcode setup claude-desktop <project> <agent> [role]", file=sys.stderr)
+                return 1
+            return setup_global(args[0], args[1], args[2], args[3] if len(args) > 3 else "")
+        # All other clients: redirect to workspace flow (no global pollution)
+        print(f"[meshcode] NOTE: 'meshcode setup {args[0]}' is deprecated. Using workspace flow.", file=sys.stderr)
         if len(args) < 3:
-            print("Usage: meshcode setup <client> <project> <agent> [role]", file=sys.stderr)
+            print("Usage: meshcode setup <project> <agent> [role]", file=sys.stderr)
             return 1
-        return setup_global(args[0], args[1], args[2], args[3] if len(args) > 3 else "")
+        return setup_workspace(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)

{meshcode-2.0.0 → meshcode-2.0.1}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.0.0
+Version: 2.0.1
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -158,6 +158,29 @@ meshcode revoke-member my-project <user> # kick a member instantly
 
 ---
 
+## Agent account management
+
+Your AI agents can manage your MeshCode account from inside the mesh. Just tell your agent what you need:
+
+- **"Create a backend agent"** → agent calls `meshcode_create_meshwork` + `meshcode_add_agent`
+- **"Change the frontend role to UI designer"** → agent calls `meshcode_edit_agent`
+- **"Give the backend agent a note about our conventions"** → agent calls `meshcode_edit_memory`
+
+Available MCP tools for agents:
+
+| Tool | What it does |
+|------|-------------|
+| `meshcode_create_meshwork(name)` | Create a new meshwork |
+| `meshcode_add_agent(name, role)` | Add an agent to the current meshwork |
+| `meshcode_edit_agent(name, role?, launch_prompt?)` | Update agent role or system prompt |
+| `meshcode_edit_memory(agent_name, key, value)` | Edit another agent's persistent memory |
+| `meshcode_scratchpad_set(key, value)` | Write to shared meshwork memory |
+| `meshcode_link(target_meshwork)` | Link two meshworks for cross-mesh communication |
+
+The agent will always tell you what CLI command to run next (e.g., "Open a new terminal and run `meshcode run backend`").
+
+---
+
 ## Editor support
 
 | Editor | Auto-detected? | Config file written |

{meshcode-2.0.0 → meshcode-2.0.1}/pyproject.toml

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