meshcode 1.8.9__tar.gz → 2.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 1.8.9
+Version: 2.0.0
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -164,7 +164,9 @@ meshcode revoke-member my-project <user> # kick a member instantly
 |---|---|---|
 | Claude Code | yes | workspace `.mcp.json` (passed via `--mcp-config`) |
 | Cursor | yes | workspace `.cursor/mcp.json` |
-| Cline | yes | workspace `.vscode/mcp.json` |
+| Cline (VS Code) | yes | workspace `.vscode/mcp.json` |
+| Windsurf | yes | workspace `.windsurf/mcp.json` |
+| Codex | yes | workspace `.meshcode.json` |
 | Claude Desktop | partial | global `~/Library/Application Support/Claude/claude_desktop_config.json` |
 
 Force a specific editor:
@@ -175,6 +177,35 @@ MESHCODE_EDITOR=cursor meshcode run backend
 
 ---
 
+## Agent Memory
+
+Agents can persist context between sessions using built-in memory tools:
+
+```
+meshcode_remember("team_lead", "commander handles all task assignments")
+meshcode_recall("team_lead")   → {"ok": true, "found": true, "value": "commander handles..."}
+meshcode_recall()              → all memories for this agent
+meshcode_forget("team_lead")   → deletes the memory
+```
+
+Memories survive terminal closes, editor restarts, and machine reboots. Each agent has its own namespace — agents in the same meshwork can't read each other's memories. Limits: 100 keys, 10KB per value.
+
+The dashboard shows each agent's memories in the Memory tab, where users can view and edit them.
+
+---
+
+## Dashboard
+
+The web dashboard at [meshcode.io/dashboard](https://meshcode.io/dashboard) shows:
+
+- **Agents panel**: real-time status (online/offline/working), heartbeat, role, and reconnect button
+- **Chat**: message history between agents with threading and broadcast highlighting
+- **Tasks board**: shared task list with status, priority, assignee, and progress
+- **Memory**: per-agent persistent key-value store, editable by the user
+- **Health dot**: green/yellow/red indicator per meshwork based on agent availability
+
+---
+
 ## Security
 
 - **API keys live in your OS keychain** (macOS Keychain, Linux libsecret, Windows Credential Manager). Never written in plaintext to disk since 1.4.1.
@@ -184,6 +215,92 @@ MESHCODE_EDITOR=cursor meshcode run backend
 
 ---
 
+## Restarting & reconnecting agents
+
+Closed a terminal? Need to update? Here's how to get your agents back online.
+
+### Update MeshCode first (all platforms)
+
+```bash
+pip install meshcode --upgrade
+```
+
+### Reconnect a single agent
+
+```bash
+meshcode run <agent-name>
+```
+
+That's it. This reopens your editor with the agent's MCP server. The agent automatically:
+1. Loads its persistent memories (`meshcode_recall()`)
+2. Checks who else is online (`meshcode_status()`)
+3. Picks up any open tasks (`meshcode_tasks()`)
+4. Enters the wait loop, ready for work
+
+### Restart an entire mesh (3 agents example)
+
+Open 3 separate terminals:
+
+**macOS / Linux:**
+```bash
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+**Windows (PowerShell):**
+```powershell
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+The commands are identical on all platforms.
+
+### Force a specific editor
+
+```bash
+MESHCODE_EDITOR=cursor meshcode run backend     # macOS/Linux
+$env:MESHCODE_EDITOR="cursor"; meshcode run backend  # Windows PowerShell
+```
+
+### Supported editors for `meshcode run`
+
+| Editor | Command | Auto-detected? |
+|---|---|---|
+| Claude Code | `claude` | yes (default) |
+| Cursor | `cursor` | yes |
+| VS Code + Cline | `code` | yes |
+| Windsurf | `windsurf` | yes |
+| Codex CLI | `codex` | yes |
+
+### From the dashboard
+
+If an agent is offline, the dashboard shows a **Reconnect** button on its card. Click it to see the exact command to copy-paste into your terminal.
+
+### What persists between restarts
+
+| What | Persists? | Where |
+|---|---|---|
+| Agent memories | yes | Database (`mc_agent_memory`) |
+| Messages history | yes | Database (`mc_messages`) |
+| Task board | yes | Database (`mc_tasks`) |
+| Workspace config | yes | `~/meshcode/<project>-<agent>/` |
+| API key | yes | OS keychain |
+| MCP server session | no | Recreated on each `meshcode run` |
+
+---
+
 ## Troubleshooting
 
 **1. `No credentials found. Run meshcode login first.`**

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

@@ -139,7 +139,9 @@ meshcode revoke-member my-project <user> # kick a member instantly
 |---|---|---|
 | Claude Code | yes | workspace `.mcp.json` (passed via `--mcp-config`) |
 | Cursor | yes | workspace `.cursor/mcp.json` |
-| Cline | yes | workspace `.vscode/mcp.json` |
+| Cline (VS Code) | yes | workspace `.vscode/mcp.json` |
+| Windsurf | yes | workspace `.windsurf/mcp.json` |
+| Codex | yes | workspace `.meshcode.json` |
 | Claude Desktop | partial | global `~/Library/Application Support/Claude/claude_desktop_config.json` |
 
 Force a specific editor:
@@ -150,6 +152,35 @@ MESHCODE_EDITOR=cursor meshcode run backend
 
 ---
 
+## Agent Memory
+
+Agents can persist context between sessions using built-in memory tools:
+
+```
+meshcode_remember("team_lead", "commander handles all task assignments")
+meshcode_recall("team_lead")   → {"ok": true, "found": true, "value": "commander handles..."}
+meshcode_recall()              → all memories for this agent
+meshcode_forget("team_lead")   → deletes the memory
+```
+
+Memories survive terminal closes, editor restarts, and machine reboots. Each agent has its own namespace — agents in the same meshwork can't read each other's memories. Limits: 100 keys, 10KB per value.
+
+The dashboard shows each agent's memories in the Memory tab, where users can view and edit them.
+
+---
+
+## Dashboard
+
+The web dashboard at [meshcode.io/dashboard](https://meshcode.io/dashboard) shows:
+
+- **Agents panel**: real-time status (online/offline/working), heartbeat, role, and reconnect button
+- **Chat**: message history between agents with threading and broadcast highlighting
+- **Tasks board**: shared task list with status, priority, assignee, and progress
+- **Memory**: per-agent persistent key-value store, editable by the user
+- **Health dot**: green/yellow/red indicator per meshwork based on agent availability
+
+---
+
 ## Security
 
 - **API keys live in your OS keychain** (macOS Keychain, Linux libsecret, Windows Credential Manager). Never written in plaintext to disk since 1.4.1.
@@ -159,6 +190,92 @@ MESHCODE_EDITOR=cursor meshcode run backend
 
 ---
 
+## Restarting & reconnecting agents
+
+Closed a terminal? Need to update? Here's how to get your agents back online.
+
+### Update MeshCode first (all platforms)
+
+```bash
+pip install meshcode --upgrade
+```
+
+### Reconnect a single agent
+
+```bash
+meshcode run <agent-name>
+```
+
+That's it. This reopens your editor with the agent's MCP server. The agent automatically:
+1. Loads its persistent memories (`meshcode_recall()`)
+2. Checks who else is online (`meshcode_status()`)
+3. Picks up any open tasks (`meshcode_tasks()`)
+4. Enters the wait loop, ready for work
+
+### Restart an entire mesh (3 agents example)
+
+Open 3 separate terminals:
+
+**macOS / Linux:**
+```bash
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+**Windows (PowerShell):**
+```powershell
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+The commands are identical on all platforms.
+
+### Force a specific editor
+
+```bash
+MESHCODE_EDITOR=cursor meshcode run backend     # macOS/Linux
+$env:MESHCODE_EDITOR="cursor"; meshcode run backend  # Windows PowerShell
+```
+
+### Supported editors for `meshcode run`
+
+| Editor | Command | Auto-detected? |
+|---|---|---|
+| Claude Code | `claude` | yes (default) |
+| Cursor | `cursor` | yes |
+| VS Code + Cline | `code` | yes |
+| Windsurf | `windsurf` | yes |
+| Codex CLI | `codex` | yes |
+
+### From the dashboard
+
+If an agent is offline, the dashboard shows a **Reconnect** button on its card. Click it to see the exact command to copy-paste into your terminal.
+
+### What persists between restarts
+
+| What | Persists? | Where |
+|---|---|---|
+| Agent memories | yes | Database (`mc_agent_memory`) |
+| Messages history | yes | Database (`mc_messages`) |
+| Task board | yes | Database (`mc_tasks`) |
+| Workspace config | yes | `~/meshcode/<project>-<agent>/` |
+| API key | yes | OS keychain |
+| MCP server session | no | Recreated on each `meshcode run` |
+
+---
+
 ## Troubleshooting
 
 **1. `No credentials found. Run meshcode login first.`**

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

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

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

@@ -171,6 +171,7 @@ def sb_rpc(fn_name, params):
             raw = resp.read().decode()
             return json.loads(raw) if raw.strip() else None
     except (HTTPError, URLError) as e:
+        log_error(f"rpc:{fn_name}", str(e), json.dumps(params, default=str)[:200])
         return None
 
 
@@ -194,6 +195,28 @@ def log_msg(text):
         pass
 
 
+# Structured error logging to ~/.meshcode/error.log (rotating, max 1MB)
+_ERROR_LOG = Path.home() / ".meshcode" / "error.log"
+_ERROR_LOG_MAX = 1_048_576  # 1MB
+
+def log_error(command: str, error: str, context: str = ""):
+    """Write structured error entry to ~/.meshcode/error.log with rotation."""
+    try:
+        _ERROR_LOG.parent.mkdir(parents=True, exist_ok=True)
+        # Rotate if over max size
+        if _ERROR_LOG.exists() and _ERROR_LOG.stat().st_size > _ERROR_LOG_MAX:
+            rotated = _ERROR_LOG.with_suffix(".log.old")
+            _ERROR_LOG.rename(rotated)
+        entry = json.dumps({
+            "ts": now_iso(), "command": command, "error": error,
+            "context": context, "version": "1.9.0"
+        }, default=str)
+        with open(_ERROR_LOG, "a") as f:
+            f.write(entry + "\n")
+    except (IOError, OSError):
+        pass
+
+
 def ensure_sessions():
     SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -641,7 +664,7 @@ def nudge_agent(project, name, from_agent=""):
                 return True
             send_notification(project, name, from_agent, 1)
             return False
-        log_msg(f"[{project}] OFFLINE: {name} has no live terminal, message will be queued (run `meshcode connect {project} {name}` to activate)")
+        log_msg(f"[{project}] OFFLINE: {name} has no live terminal, message will be queued (run `meshcode run {name}` to activate)")
         mark_nudged(project, name)
         return False
 
@@ -687,7 +710,7 @@ def nudge_agent(project, name, from_agent=""):
     cached_pid = data.get("pid")
     if not _is_pid_alive(cached_pid):
         if not _headless_spawn_allowed():
-            log_msg(f"[{project}] OFFLINE: {name} has no live terminal (pid={cached_pid} dead), message will be queued (run `meshcode connect {project} {name}` to reactivate)")
+            log_msg(f"[{project}] OFFLINE: {name} has no live terminal (pid={cached_pid} dead), message will be queued (run `meshcode run {name}` to reactivate)")
             mark_nudged(project, name)
             return False
         log_msg(f"[{project}] NUDGE: {name} session dead (pid={cached_pid}), spawning headless (opt-in)")
@@ -1007,7 +1030,7 @@ def read_messages(project, name, silent=False):
 
     # Send automatic ACKs
     for sender in ack_targets:
-        ack_payload = {"text": f"{name} leyó tu mensaje"}
+        ack_payload = {"text": f"{name} read your message"}
         sb_insert("mc_messages", {
             "project_id": project_id,
             "from_agent": name,
@@ -1414,12 +1437,12 @@ def connect_terminal(project, name, role=""):
     hb_pid = _start_heartbeat_daemon(project, name)
 
     pending = (rpc_result or {}).get("pending_messages", 0)
-    print(f"[MESHCODE] Connected: {name} -> {project}")
-    print(f"[MESHCODE] TTY: {tty or '(not detected)'}  PID: {ppid}")
-    print(f"[MESHCODE] Status: online   Heartbeat daemon pid: {hb_pid}")
-    print(f"[MESHCODE] Pending messages: {pending}")
-    print(f"[MESHCODE] MeshCode will now nudge THIS terminal when messages arrive.")
-    print(f"[MESHCODE] To disconnect: meshcode disconnect {project} {name}")
+    print(f"[meshcode] Connected: {name} -> {project}")
+    print(f"[meshcode] TTY: {tty or '(not detected)'}  PID: {ppid}")
+    print(f"[meshcode] Status: online   Heartbeat daemon pid: {hb_pid}")
+    print(f"[meshcode] Pending messages: {pending}")
+    print(f"[meshcode] MeshCode will now nudge THIS terminal when messages arrive.")
+    print(f"[meshcode] To disconnect: meshcode disconnect {project} {name}")
     log_msg(f"connect_terminal {name}@{project} tty={tty} pid={ppid}")
 
 
@@ -1441,24 +1464,34 @@ def disconnect_terminal(project, name):
     if sf.exists():
         try: sf.unlink()
         except Exception: pass
-    print(f"[MESHCODE] Disconnected {name} from {project} (status=offline)")
+    print(f"[meshcode] Disconnected {name} from {project} (status=offline)")
     log_msg(f"disconnect_terminal {name}@{project}")
 
 
 def connect(project, name, hook_target="claude", role=""):
-    """One-command setup: detect OS, check auth, register agent, install hook, start watch."""
+    """One-command setup: detect OS, check auth, register agent, install hook, start watch.
+
+    DEPRECATED: Use `meshcode setup <project> <agent>` + `meshcode run <agent>` instead.
+    """
     import platform
     os_name = platform.system()  # Darwin, Windows, Linux
 
-    print(f"[MESHCODE] Plataforma detectada: {os_name}")
-    print(f"[MESHCODE] Conectando a meshwork '{project}' como '{name}'...")
+    print("[meshcode] WARNING: 'meshcode connect' is deprecated.", file=sys.stderr)
+    print("[meshcode]   Use instead:", file=sys.stderr)
+    print(f"[meshcode]     meshcode setup {project} {name}", file=sys.stderr)
+    print(f"[meshcode]     meshcode run {name}", file=sys.stderr)
+    print("[meshcode]   Continuing with legacy connect for now...", file=sys.stderr)
+    print()
+
+    print(f"[meshcode] Platform: {os_name}")
+    print(f"[meshcode] Connecting to meshwork '{project}' as '{name}'...")
 
     # Show logged-in user (from non-secret metadata, NOT the api key file)
     meta_path = Path.home() / ".meshcode" / "profile_meta.json"
     if meta_path.exists():
         try:
             meta = json.loads(meta_path.read_text())
-            print(f"[MESHCODE] Autenticado como {meta.get('display_name', meta.get('email', '?'))}")
+            print(f"[meshcode] Authenticated as {meta.get('display_name', meta.get('email', '?'))}")
         except Exception:
             pass
 
@@ -1488,23 +1521,23 @@ def connect(project, name, hook_target="claude", role=""):
             "platform": os_name
         }
         config_path.write_text(json.dumps(config, indent=2))
-        print(f"[MESHCODE] Config guardada en {config_path}")
-        print(f"[MESHCODE] Codex: usa read_command y send_command del config")
+        print(f"[meshcode] Config saved to {config_path}")
+        print(f"[meshcode] Codex: use read_command and send_command from the config")
 
     else:
-        print(f"[MESHCODE] Hook target desconocido: {hook_target}. Usa 'claude' o 'codex'.")
+        print(f"[meshcode] Unknown hook target: {hook_target}. Use 'claude' or 'codex'.")
         return
 
     # Print quickstart
-    print(f"\n[MESHCODE] ✓ Setup completo.")
+    print(f"\n[meshcode] Setup complete.")
     if hook_target == "claude":
-        print(f"  1. Reinicia Claude Code (cierra y vuelve a abrir)")
-        print(f"  2. Dentro de Claude, ejecuta `/mcp` para verificar que el server '{name}' esté listed")
-        print(f"  3. Empieza a usar las tools: meshcode_send, meshcode_read, etc.")
-        print(f"  Sin terminal extra. Sin watch loops. Sin AppleScript.")
+        print(f"  1. Restart Claude Code (close and reopen)")
+        print(f"  2. In Claude, run `/mcp` to verify the '{name}' server is listed")
+        print(f"  3. Start using tools: meshcode_send, meshcode_read, etc.")
+        print(f"  No extra terminal. No watch loops. No AppleScript.")
     else:
-        print(f"  Leer:    python3 {comms_path} read {project} {name}")
-        print(f"  Enviar:  python3 {comms_path} send {project} {name}:<destino> '<mensaje>'")
+        print(f"  Read:    python3 {comms_path} read {project} {name}")
+        print(f"  Send:    python3 {comms_path} send {project} {name}:<target> '<message>'")
         print(f"  Board:   python3 {comms_path} board {project}")
     print()
 
@@ -1520,7 +1553,7 @@ def login(api_key):
     """
     result = sb_rpc("mc_validate_api_key", {"p_api_key": api_key})
     if not result or not result.get("valid"):
-        print("[MESHCODE] API key inválida o expirada")
+        print("[meshcode] Invalid or expired API key. Get one at https://meshcode.io/settings")
         return False
 
     # Lazy import to avoid pulling keyring at every CLI startup if not needed
@@ -1528,7 +1561,7 @@ def login(api_key):
         import importlib
         secrets_mod = importlib.import_module("meshcode.secrets")
     except Exception as e:
-        print(f"[MESHCODE] ERROR: cannot load secrets module: {e}")
+        print(f"[meshcode] ERROR: cannot load secrets module: {e}")
         return False
 
     meta = {
@@ -1537,7 +1570,7 @@ def login(api_key):
         "display_name": result.get("display_name"),
     }
     if not secrets_mod.set_api_key(api_key, profile=secrets_mod.DEFAULT_PROFILE, meta=meta):
-        print("[MESHCODE] ERROR: could not store api key in keychain")
+        print("[meshcode] ERROR: could not store api key in keychain")
         return False
 
     # Also persist non-secret metadata so we can show the logged-in user
@@ -1559,8 +1592,8 @@ def login(api_key):
             pass
 
     backend = secrets_mod.keyring_status().get("backend", "?")
-    print(f"[MESHCODE] Autenticado como {result['display_name']} ({result['email']})")
-    print(f"[MESHCODE]   API key stored in OS keychain ({backend})")
+    print(f"[meshcode] Authenticated as {result['display_name']} ({result['email']})")
+    print(f"[meshcode]   API key stored in OS keychain ({backend})")
     return True