meshcode 1.0.0__py3-none-any.whl

meshcode/comms_v4.py

@@ -0,0 +1,1208 @@
+#!/usr/bin/env python3
+"""
+AICOMMS v4 — Supabase-backed Real-time Inter-Agent Communication
+=================================================================
+Drop-in replacement for comms.py (v3). Same CLI interface, same output format.
+Backend: Supabase REST API (meshcode schema) instead of local files.
+Realtime: Supabase Realtime via publication on mc_messages + mc_agents.
+
+COMMANDS (identical to v3):
+  register <project> <name> [role]        Join a project network
+  send <project> <from>:<to> <message>    Send message within project
+  broadcast <project> <from> <message>    Send to all agents in project
+  read <project> <name>                   Read pending messages
+  check                                   Hook auto-check (silent if empty)
+  watch <project> <name> [interval] [timeout]  BLOCKING wait for messages
+  board <project>                         Project status board
+  update <project> <name> <status> [task] Update board status
+  history <project> [count] [agent1,agent2]  Conversation log
+  status [project]                        System overview
+  clear <project> <name>                  Clear inbox
+  unregister <project> <name>             Leave project
+  projects                                List all active projects
+"""
+
+import json
+import os
+import sys
+import time
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+from urllib.parse import quote
+
+# ============================================================
+# CONFIG — Supabase connection
+# ============================================================
+SUPABASE_URL = os.environ.get(
+    "SUPABASE_URL",
+    "https://wwgzzmydrwrjgaebspdo.supabase.co"
+)
+SUPABASE_KEY = os.environ.get(
+    "SUPABASE_KEY",
+    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Ind3Z3p6bXlkcndyamdhZWJzcGRvIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc2NzY1NDc3MCwiZXhwIjoyMDgzMjMwNzcwfQ.0SBXfb8OtyHmfaKW3dFQ6JYbcLUzCS1d4oXg4V-RAag"
+)
+SCHEMA = "meshcode"
+
+# Local paths for session/TTY tracking (still needed for nudge)
+COMMS_DIR = Path(__file__).parent
+SESSIONS_DIR = COMMS_DIR / "sessions"
+LOG_FILE = COMMS_DIR / "comms.log"
+
+# ============================================================
+# SUPABASE REST HELPERS (stdlib only — zero dependencies)
+# ============================================================
+
+def _headers(*, prefer=None, content_profile=True):
+    """Build headers for Supabase REST API."""
+    h = {
+        "apikey": SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type": "application/json",
+    }
+    if content_profile:
+        h["Accept-Profile"] = SCHEMA
+        h["Content-Profile"] = SCHEMA
+    if prefer:
+        h["Prefer"] = prefer
+    return h
+
+
+def _request(method, path, *, data=None, prefer=None):
+    """Make HTTP request to Supabase REST API. Returns parsed JSON or None."""
+    url = f"{SUPABASE_URL}/rest/v1/{path}"
+    body = json.dumps(data).encode() if data else None
+    req = Request(url, data=body, method=method, headers=_headers(prefer=prefer))
+    try:
+        with urlopen(req, timeout=10) as resp:
+            raw = resp.read().decode()
+            return json.loads(raw) if raw.strip() else None
+    except HTTPError as e:
+        err = e.read().decode()
+        # Try to extract trigger / RPC error message for clarity
+        try:
+            err_obj = json.loads(err)
+            msg = err_obj.get("message", err[:200])
+            # Daily message limit trigger raises a friendly message
+            if "Daily message limit reached" in msg:
+                print(f"[QUOTA] {msg}", file=sys.stderr)
+            else:
+                print(f"[ERROR] {method} {path}: {e.code} {msg}", file=sys.stderr)
+        except Exception:
+            print(f"[ERROR] {method} {path}: {e.code} {err[:200]}", file=sys.stderr)
+        return None
+    except URLError as e:
+        print(f"[ERROR] Network: {e.reason}", file=sys.stderr)
+        return None
+
+
+def sb_select(table, filters="", order=None, limit=None):
+    """SELECT from meshcode.table with PostgREST filters."""
+    params = []
+    if filters:
+        params.append(filters)
+    if order:
+        params.append(f"order={order}")
+    if limit:
+        params.append(f"limit={limit}")
+    path = f"{table}?{'&'.join(params)}" if params else table
+    return _request("GET", path) or []
+
+
+def sb_insert(table, row, *, upsert=False, on_conflict=None):
+    """INSERT into meshcode.table. Returns inserted row."""
+    prefer = "return=representation"
+    if upsert:
+        prefer += ",resolution=merge-duplicates"
+    path = table
+    if on_conflict:
+        path += f"?on_conflict={on_conflict}"
+    return _request("POST", path, data=row, prefer=prefer)
+
+
+def sb_update(table, filters, updates):
+    """UPDATE meshcode.table SET updates WHERE filters."""
+    path = f"{table}?{filters}"
+    return _request("PATCH", path, data=updates, prefer="return=representation")
+
+
+def sb_delete(table, filters):
+    """DELETE FROM meshcode.table WHERE filters."""
+    path = f"{table}?{filters}"
+    return _request("DELETE", path, prefer="return=representation")
+
+
+def sb_rpc(fn_name, params):
+    """Call a Supabase RPC function."""
+    url = f"{SUPABASE_URL}/rest/v1/rpc/{fn_name}"
+    body = json.dumps(params).encode()
+    req = Request(url, data=body, method="POST", headers=_headers(content_profile=False))
+    try:
+        with urlopen(req, timeout=10) as resp:
+            raw = resp.read().decode()
+            return json.loads(raw) if raw.strip() else None
+    except (HTTPError, URLError) as e:
+        return None
+
+
+# ============================================================
+# HELPERS
+# ============================================================
+
+def now():
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def now_iso():
+    return datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S+00:00")
+
+
+def log_msg(text):
+    try:
+        with open(LOG_FILE, "a") as f:
+            f.write(f"[{now()}] {text}\n")
+    except:
+        pass
+
+
+def ensure_sessions():
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_project_id(project_name):
+    """Get or create project, return its UUID."""
+    rows = sb_select("mc_projects", f"name=eq.{quote(project_name)}")
+    if rows:
+        return rows[0]["id"]
+    # Create project
+    result = sb_insert("mc_projects", {"name": project_name})
+    if result and len(result) > 0:
+        return result[0]["id"]
+    return None
+
+
+# ============================================================
+# NUDGE (same as v3 — local AppleScript)
+# ============================================================
+
+NUDGE_COOLDOWN = 10
+
+def get_nudge_file(project, name):
+    return SESSIONS_DIR / f".nudge_{project}_{name}" if SESSIONS_DIR.exists() else None
+
+
+def can_nudge(project, name):
+    nf = get_nudge_file(project, name)
+    if nf and nf.exists():
+        try:
+            last = float(nf.read_text().strip())
+            if (time.time() - last) < NUDGE_COOLDOWN:
+                return False
+        except:
+            pass
+    return True
+
+
+def mark_nudged(project, name):
+    nf = get_nudge_file(project, name)
+    if nf:
+        nf.write_text(str(time.time()))
+
+
+def send_notification(project, name, from_agent, pending=1):
+    """Cross-platform notification: macOS (osascript), Windows (PowerShell toast), Linux (notify-send)."""
+    title = f"MeshCode [{project}] → {name}"
+    body = f"{pending} mensaje(s) pendiente(s) de {from_agent}"
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(['osascript', '-e',
+                f'display notification "{body}" with title "{title}" sound name "Ping"'],
+                capture_output=True, timeout=3)
+        elif sys.platform == "win32":
+            ps_script = (
+                f'[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null; '
+                f'$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(0); '
+                f'$text = $xml.GetElementsByTagName("text"); '
+                f'$text[0].AppendChild($xml.CreateTextNode("{title}")); '
+                f'$text[1].AppendChild($xml.CreateTextNode("{body}")); '
+                f'$toast = [Windows.UI.Notifications.ToastNotification]::new($xml); '
+                f'[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("MeshCode").Show($toast)'
+            )
+            subprocess.run(['powershell', '-Command', ps_script],
+                capture_output=True, timeout=5)
+        else:
+            # Linux
+            subprocess.run(['notify-send', title, body], capture_output=True, timeout=3)
+    except:
+        pass
+
+
+def nudge_agent(project, name, from_agent=""):
+    if not can_nudge(project, name):
+        return False
+
+    ensure_sessions()
+    session_file = SESSIONS_DIR / f"{project}_{name}"
+    if not session_file.exists():
+        send_notification(project, name, from_agent, 1)
+        return False
+
+    try:
+        data = json.loads(session_file.read_text())
+    except:
+        send_notification(project, name, from_agent, 1)
+        return False
+
+    tty = data.get("tty")
+    if not tty:
+        send_notification(project, name, from_agent, 1)
+        return False
+
+    # Count pending from Supabase
+    project_id = get_project_id(project)
+    pending_msgs = sb_select("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false&type=neq.ack",
+        limit=100)
+    pending = len(pending_msgs) if pending_msgs else 1
+
+    message = f"Tienes {pending} mensaje(s). Revisa: meshcode read {project} {name}"
+    escaped_message = message.replace('\\', '\\\\').replace('"', '\\"')
+
+    # Only attempt AppleScript nudge on macOS
+    if sys.platform != "darwin":
+        send_notification(project, name, from_agent, pending)
+        mark_nudged(project, name)
+        return True
+
+    # Use `do script in tab` — writes command DIRECTLY to the target tab
+    # without keystroke injection or focus changes. The user's foreground
+    # app stays active. Works even if Terminal is in background.
+    applescript_terminal = f'''
+tell application "Terminal"
+    set targetTab to missing value
+    repeat with w in windows
+        repeat with t in tabs of w
+            try
+                if tty of t contains "{tty}" then
+                    set targetTab to t
+                    exit repeat
+                end if
+            end try
+        end repeat
+        if targetTab is not missing value then exit repeat
+    end repeat
+    if targetTab is not missing value then
+        do script "{escaped_message}" in targetTab
+    else
+        error "tty not found"
+    end if
+end tell
+'''
+    success = False
+    try:
+        result = subprocess.run(['osascript', '-e', applescript_terminal],
+                              capture_output=True, text=True, timeout=10)
+        if result.returncode == 0:
+            success = True
+    except:
+        pass
+
+    if success:
+        mark_nudged(project, name)
+        log_msg(f"[{project}] NUDGE: {name} woken ({pending} pending)")
+        return True
+
+    mark_nudged(project, name)
+    send_notification(project, name, from_agent, pending)
+    log_msg(f"[{project}] NUDGE: {name} via notification (keystroke failed)")
+    return False
+
+
+def get_session_info():
+    """Detect which agent+project this session is via TTY matching."""
+    ensure_sessions()
+    my_tty = None
+    try:
+        check_pid = os.getpid()
+        for _ in range(8):
+            result = subprocess.check_output(['ps', '-p', str(check_pid), '-o', 'tty=,ppid='],
+                                            text=True, timeout=3).strip()
+            parts = result.split()
+            if len(parts) >= 2:
+                tty_val = parts[0]
+                parent = parts[1]
+                if tty_val and tty_val != '??' and tty_val != '':
+                    my_tty = tty_val
+                    break
+                check_pid = parent
+            else:
+                break
+    except:
+        pass
+
+    if not my_tty:
+        return None, None
+
+    for f in SESSIONS_DIR.iterdir():
+        if f.is_file() and '_' in f.name and not f.name.startswith('.'):
+            try:
+                data = json.loads(f.read_text())
+                session_tty = data.get("tty", "")
+                if session_tty and (session_tty in my_tty or my_tty in session_tty):
+                    return data.get("project"), data.get("agent")
+            except:
+                continue
+
+    return None, None
+
+
+# ============================================================
+# COMMANDS
+# ============================================================
+
+def register(project, name, role=""):
+    ensure_sessions()
+    project_id = get_project_id(project)
+    if not project_id:
+        print(f"[ERROR] No se pudo crear/encontrar proyecto '{project}'")
+        return
+
+    ppid = os.getppid()
+
+    # Capture TTY
+    tty = None
+    try:
+        check_pid = ppid
+        for _ in range(5):
+            result = subprocess.check_output(['ps', '-p', str(check_pid), '-o', 'tty=,ppid='],
+                                            text=True, timeout=3).strip()
+            parts = result.split()
+            if len(parts) >= 2:
+                tty_val = parts[0]
+                parent = parts[1]
+                if tty_val and tty_val != '??' and tty_val != '':
+                    tty = tty_val
+                    break
+                check_pid = parent
+            else:
+                break
+    except:
+        pass
+
+    # Register agent via tier-aware RPC (enforces plan limits)
+    rpc_result = sb_rpc("mc_register_agent", {
+        "p_project_id": project_id,
+        "p_name": name,
+        "p_role": role,
+        "p_status": "online"
+    })
+
+    if rpc_result and rpc_result.get("error"):
+        print(f"[ERROR] {rpc_result['error']}")
+        if rpc_result.get("upgrade_url"):
+            print(f"[ERROR] Upgrade: {rpc_result['upgrade_url']}")
+        if rpc_result.get("current") is not None:
+            print(f"[ERROR] Agentes: {rpc_result['current']} / {rpc_result.get('max', '?')}")
+        return
+
+    # Update tty/pid (RPC doesn't take these — patch separately)
+    sb_update("mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{quote(name)}",
+        {"tty": tty, "pid": ppid, "task": role, "last_heartbeat": now_iso()})
+
+    # Save local session file (for nudge TTY detection)
+    session_data = {"project": project, "agent": name, "pid": ppid, "tty": tty, "registered_at": now()}
+    (SESSIONS_DIR / f"{project}_{name}").write_text(json.dumps(session_data))
+
+    # Get all agents in project
+    agents = sb_select("mc_agents", f"project_id=eq.{project_id}", order="registered_at.asc")
+    agent_names = [a["name"] for a in agents]
+
+    # Count pending messages
+    pending_msgs = sb_select("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false&type=neq.ack")
+    pending = len(pending_msgs)
+
+    print(f"[COMMS] Proyecto: {project}")
+    print(f"[COMMS] Registrado: {name} ({role})")
+    print(f"[COMMS] TTY: {tty or 'no detectado'}")
+    print(f"[COMMS] Online en {project}: {', '.join(agent_names)}")
+    print(f"[COMMS] Auto-nudge: {'activado' if tty else 'solo notificaciones (sin TTY)'}")
+    print(f"[COMMS] Backend: Supabase ({SCHEMA} schema)")
+    if pending > 0:
+        print(f"[COMMS] Tienes {pending} mensaje(s) pendiente(s) — ejecuta read para verlos")
+
+    # Show recent history
+    recent = sb_select("mc_messages",
+        f"project_id=eq.{project_id}&type=neq.ack",
+        order="created_at.desc", limit=10)
+    if recent:
+        recent.reverse()
+        print(f"\n[COMMS] Últimos {len(recent)} mensajes del equipo:")
+        for msg in recent:
+            ts = msg.get("created_at", "")[-8:]
+            fr = msg["from_agent"]
+            to = msg["to_agent"]
+            payload = msg.get("payload", {})
+            preview = json.dumps(payload, ensure_ascii=False)[:80]
+            print(f"  [{ts}] {fr}->{to}: {preview}")
+        print()
+
+    log_msg(f"{name} joined {project} (tty={tty}, backend=supabase)")
+
+
+def send_msg(project, from_agent, to_agent, content, msg_type="msg"):
+    project_id = get_project_id(project)
+    if not project_id:
+        print(f"[ERROR] Proyecto '{project}' no encontrado")
+        return
+
+    payload = {}
+    try:
+        payload = json.loads(content)
+    except (json.JSONDecodeError, TypeError):
+        payload = {"text": content}
+
+    msg = {
+        "project_id": project_id,
+        "from_agent": from_agent,
+        "to_agent": to_agent,
+        "type": msg_type,
+        "payload": payload,
+        "read": False
+    }
+
+    result = sb_insert("mc_messages", msg)
+    if result:
+        preview = json.dumps(payload, ensure_ascii=False)[:60]
+        log_msg(f"[{project}] {from_agent}->{to_agent}: {preview}")
+        print(f"[{project}] {from_agent}->{to_agent}: sent")
+
+        # Nudge idle agents (skip acks)
+        if msg_type not in ("ack", "warning") and from_agent != "system":
+            agents = sb_select("mc_agents",
+                f"project_id=eq.{project_id}&name=eq.{quote(to_agent)}")
+            if agents and agents[0].get("status") in ("idle", "standby", "online"):
+                nudge_agent(project, to_agent, from_agent)
+    else:
+        print(f"[{project}] ERROR: no se pudo enviar mensaje")
+
+
+def broadcast(project, from_agent, content, msg_type="broadcast"):
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+    agents = sb_select("mc_agents", f"project_id=eq.{project_id}")
+    count = 0
+    for agent in agents:
+        if agent["name"] != from_agent:
+            send_msg(project, from_agent, agent["name"], content, msg_type)
+            count += 1
+            time.sleep(1.5)
+    print(f"[{project}] broadcast from {from_agent} -> {count} agents")
+
+
+def read_messages(project, name, silent=False):
+    project_id = get_project_id(project)
+    if not project_id:
+        if not silent:
+            print("[EMPTY]")
+        return []
+
+    # Get unread messages
+    messages = sb_select("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false",
+        order="created_at.asc")
+
+    if not messages:
+        if not silent:
+            print("[EMPTY]")
+        return []
+
+    # Mark all as read
+    msg_ids = [m["id"] for m in messages]
+    for mid in msg_ids:
+        sb_update("mc_messages", f"id=eq.{mid}", {"read": True})
+
+    print(f"[{project}] {len(messages)} mensaje(s) para {name}:")
+    print("---")
+    ack_targets = set()
+    for msg in messages:
+        sender = msg["from_agent"]
+        mtype = msg.get("type", "msg")
+        ts = msg.get("created_at", "")
+        # Format timestamp to match v3
+        if "T" in ts:
+            ts = ts.replace("T", " ")[:19]
+        payload = msg.get("payload", {})
+        print(f"[{sender}|{mtype}|{ts}] {json.dumps(payload, ensure_ascii=False)}")
+        if mtype not in ("ack", "broadcast") and sender != name:
+            ack_targets.add(sender)
+    print("---")
+
+    # Send automatic ACKs
+    for sender in ack_targets:
+        ack_payload = {"text": f"{name} leyó tu mensaje"}
+        sb_insert("mc_messages", {
+            "project_id": project_id,
+            "from_agent": name,
+            "to_agent": sender,
+            "type": "ack",
+            "payload": ack_payload,
+            "read": False
+        })
+
+    return messages
+
+
+def hook_check():
+    """Called by PostToolUse hook. Auto-detects project+agent, prints pending.
+    Also sends heartbeat so dashboard always shows fresh status."""
+    ensure_sessions()
+    project, agent = get_session_info()
+    if not project or not agent:
+        return
+
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+
+    # Always heartbeat — keeps agent alive on dashboard
+    sb_update("mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{quote(agent)}",
+        {"status": "working", "last_heartbeat": now_iso()})
+
+    # Check for unread non-ack messages
+    pending = sb_select("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(agent)}&read=eq.false&type=neq.ack",
+        limit=1)
+
+    if not pending:
+        return
+
+    count = len(sb_select("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(agent)}&read=eq.false&type=neq.ack"))
+
+    print(f"\n*** [{project.upper()}] {count} MENSAJE(S) para {agent} ***")
+    read_messages(project, agent, silent=False)
+    print(f"*** Lee y responde via meshcode. ***\n")
+
+
+def watch(project, name, interval=10, timeout=0):
+    """BLOCKING wait for messages. Auto-loops: returns on message, auto-restarts after cycle."""
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+
+    import signal
+    _interrupted = [False]
+    def handle_interrupt(signum, frame):
+        _interrupted[0] = True
+        print(f"\n[{project}] {name}: Watch interrumpido por el usuario.")
+        sb_update("mc_agents",
+            f"project_id=eq.{project_id}&name=eq.{quote(name)}",
+            {"status": "online", "task": "Listening to user", "last_heartbeat": now_iso()})
+        sys.exit(0)
+    signal.signal(signal.SIGINT, handle_interrupt)
+
+    # Update status to standby
+    sb_update("mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{quote(name)}",
+        {"status": "standby", "task": "Esperando mensajes...", "last_heartbeat": now_iso()})
+
+    cycle = timeout if timeout > 0 else 600
+    print(f"[{project}] {name} en watch — poll cada {interval}s, ciclo {cycle}s (auto-loop)")
+
+    while not _interrupted[0]:
+        start = time.time()
+
+        while (time.time() - start) < cycle and not _interrupted[0]:
+            pending = sb_select("mc_messages",
+                f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false&type=neq.ack",
+                limit=1)
+
+            if pending:
+                elapsed = int(time.time() - start)
+                print(f"\n*** [{project.upper()}] MENSAJE RECIBIDO ({elapsed}s en standby) ***")
+                messages = read_messages(project, name, silent=False)
+
+                sb_update("mc_agents",
+                    f"project_id=eq.{project_id}&name=eq.{quote(name)}",
+                    {"status": "working", "task": "Procesando mensaje recibido", "last_heartbeat": now_iso()})
+
+                return messages
+
+            # Heartbeat
+            sb_rpc("mc_heartbeat", {"p_project_id": project_id, "p_agent_name": name})
+            time.sleep(interval)
+
+        # Cycle ended without messages — check user context, then AUTO-RESTART watch
+        print(f"[{project}] Otro ciclo sin mensajes. Watch activo, sigue corriendo. En standby.")
+        sb_update("mc_agents",
+            f"project_id=eq.{project_id}&name=eq.{quote(name)}",
+            {"status": "standby", "task": "Esperando mensajes...", "last_heartbeat": now_iso()})
+
+
+def update_board(project, name, status, task=""):
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+
+    # Block idle if there are unread messages
+    if status == "idle":
+        pending = sb_select("mc_messages",
+            f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false&type=neq.ack",
+            limit=1)
+        if pending:
+            count = len(sb_select("mc_messages",
+                f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false&type=neq.ack"))
+            print(f"[{project}] {name}: NO puedes estar idle — tienes {count} mensaje(s) pendientes.")
+            print(f"[{project}] Ejecuta: python3 ~/Desktop/meshcode/comms_v4.py read {project} {name}")
+            status = "working"
+            task = f"{count} mensajes pendientes"
+
+    updates = {"status": status, "last_heartbeat": now_iso()}
+    if task:
+        updates["task"] = task
+
+    sb_update("mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{quote(name)}", updates)
+    print(f"[{project}] {name}: {status} — {task}")
+
+
+def show_board(project):
+    project_id = get_project_id(project)
+    if not project_id:
+        print(f"[{project}] Sin proyecto")
+        return
+
+    agents = sb_select("mc_agents", f"project_id=eq.{project_id}", order="registered_at.asc")
+    if not agents:
+        print(f"[{project}] Sin agentes")
+        return
+
+    print(f"\n{'='*60}")
+    print(f" {project.upper()} — Board")
+    print(f"{'='*60}")
+    for a in agents:
+        icon = {"online": "●", "working": "▶", "blocked": "■", "standby": "◆", "idle": "○", "done": "✓"}.get(a.get("status", ""), "?")
+        print(f"  {icon} {a['name']:<14} {a.get('status','?'):<10} {a.get('task','')}")
+    print()
+
+
+def show_status(project=None):
+    if project:
+        projects_data = sb_select("mc_projects", f"name=eq.{quote(project)}")
+    else:
+        projects_data = sb_select("mc_projects", "", order="created_at.asc")
+
+    if not projects_data:
+        print("[COMMS] Sin proyectos activos")
+        return
+
+    print(f"\n{'='*60}")
+    print(f" AICOMMS v4 STATUS (Supabase)")
+    print(f"{'='*60}")
+
+    for proj in projects_data:
+        agents = sb_select("mc_agents", f"project_id=eq.{proj['id']}", order="name.asc")
+        if not agents:
+            continue
+
+        print(f"\n  [{proj['name']}]")
+        for a in agents:
+            # Count pending
+            pending = sb_select("mc_messages",
+                f"project_id=eq.{proj['id']}&to_agent=eq.{quote(a['name'])}&read=eq.false&type=neq.ack")
+            pcount = len(pending)
+            icon = "●" if pcount > 0 else "○"
+            print(f"    {icon} {a['name']:<14} {a.get('role',''):<25} pending: {pcount}")
+    print()
+
+
+def show_history(project, last_n=20, between=None):
+    project_id = get_project_id(project)
+    if not project_id:
+        print(f"[{project}] Sin historial")
+        return
+
+    filters = f"project_id=eq.{project_id}&type=neq.ack"
+    if between:
+        agents = between.split(",")
+        if len(agents) == 2:
+            a, b = agents
+            # PostgREST OR filter
+            filters += f"&or=(and(from_agent.eq.{quote(a)},to_agent.eq.{quote(b)}),and(from_agent.eq.{quote(b)},to_agent.eq.{quote(a)}))"
+
+    messages = sb_select("mc_messages", filters, order="created_at.desc", limit=last_n)
+    if not messages:
+        print(f"[{project}] Sin historial")
+        return
+
+    messages.reverse()
+
+    print(f"\n{'='*60}")
+    print(f" {project.upper()} — Historial ({len(messages)} mensajes)")
+    if between:
+        print(f" Filtro: {between}")
+    print(f"{'='*60}\n")
+
+    for msg in messages:
+        ts = msg.get("created_at", "")
+        if "T" in ts:
+            ts = ts.replace("T", " ")[:19]
+        sender = msg.get("from_agent", "?")
+        to = msg.get("to_agent", "?")
+        payload = msg.get("payload", {})
+        content = json.dumps(payload, ensure_ascii=False)
+        print(f"  [{ts}] {sender}->{to}: {content}")
+    print()
+
+
+def list_projects():
+    projects_data = sb_select("mc_projects", "", order="created_at.asc")
+    if not projects_data:
+        print("[COMMS] Sin proyectos")
+        return
+
+    print(f"\n{'='*60}")
+    print(f" PROYECTOS ACTIVOS (Supabase)")
+    print(f"{'='*60}")
+
+    for proj in projects_data:
+        agents = sb_select("mc_agents", f"project_id=eq.{proj['id']}", order="name.asc")
+        statuses = [f"{a['name']}({a.get('status','?')})" for a in agents]
+        print(f"  [{proj['name']}] {', '.join(statuses) if statuses else 'sin agentes'}")
+    print()
+
+
+def clear_inbox(project, name):
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+    # Mark all as read
+    sb_update("mc_messages",
+        f"project_id=eq.{project_id}&to_agent=eq.{quote(name)}&read=eq.false",
+        {"read": True})
+    print(f"[{project}] {name} inbox cleared")
+
+
+def unregister(project, name):
+    project_id = get_project_id(project)
+    if not project_id:
+        return
+    sb_delete("mc_agents", f"project_id=eq.{project_id}&name=eq.{quote(name)}")
+
+    # Clean local session
+    session_file = SESSIONS_DIR / f"{project}_{name}"
+    if session_file.exists():
+        session_file.unlink()
+
+    log_msg(f"{name} left {project}")
+    print(f"[{project}] {name} removed")
+
+
+def connect(project, name, hook_target="claude", role=""):
+    """One-command setup: detect OS, check auth, register agent, install hook, start watch."""
+    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}'...")
+
+    # Check for saved credentials
+    creds_path = Path.home() / ".meshcode" / "credentials.json"
+    if creds_path.exists():
+        try:
+            creds = json.loads(creds_path.read_text())
+            print(f"[MESHCODE] Autenticado como {creds.get('display_name', creds.get('email', '?'))}")
+        except:
+            pass
+
+    # Register agent
+    actual_role = role or f"Connected via meshcode connect ({hook_target})"
+    register(project, name, actual_role)
+
+    # Install hook based on target
+    comms_path = str(Path(__file__).resolve())
+
+    if hook_target == "claude":
+        settings_path = Path.home() / ".claude" / "settings.json"
+        hook_cmd = f"python3 {comms_path} check"
+
+        settings = {}
+        if settings_path.exists():
+            try:
+                settings = json.loads(settings_path.read_text())
+            except:
+                pass
+
+        hooks = settings.setdefault("hooks", {})
+        post_hooks = hooks.setdefault("PostToolUse", [])
+
+        already = any(hook_cmd in h.get("command", "") for h in post_hooks)
+        if not already:
+            post_hooks.append({"command": hook_cmd, "matcher": ""})
+            settings_path.parent.mkdir(parents=True, exist_ok=True)
+            settings_path.write_text(json.dumps(settings, indent=2))
+            print(f"[MESHCODE] Hook PostToolUse instalado en {settings_path}")
+        else:
+            print(f"[MESHCODE] Hook PostToolUse ya existe")
+
+        print(f"[MESHCODE] Claude Code conectado a {project} como {name}")
+
+    elif hook_target == "codex":
+        config_path = Path.cwd() / ".meshcode.json"
+        config = {
+            "project": project,
+            "agent": name,
+            "supabase_url": SUPABASE_URL,
+            "check_command": f"python3 {comms_path} check",
+            "read_command": f"python3 {comms_path} read {project} {name}",
+            "send_command": f"python3 {comms_path} send {project} {name}:{{to}} '{{message}}'",
+            "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")
+
+    else:
+        print(f"[MESHCODE] Hook target desconocido: {hook_target}. Usa 'claude' o 'codex'.")
+        return
+
+    # Print quickstart
+    print(f"\n[MESHCODE] ✓ Setup completo. Comandos útiles:")
+    print(f"  Leer:    python3 {comms_path} read {project} {name}")
+    print(f"  Enviar:  python3 {comms_path} send {project} {name}:<destino> '<mensaje>'")
+    print(f"  Board:   python3 {comms_path} board {project}")
+    print(f"  Watch:   python3 {comms_path} watch {project} {name}")
+    print()
+
+
+def login(api_key):
+    """Authenticate with API key and save credentials locally."""
+    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")
+        return False
+
+    # Save credentials
+    config_dir = Path.home() / ".meshcode"
+    config_dir.mkdir(exist_ok=True)
+    creds = {
+        "api_key": api_key,
+        "user_id": result["user_id"],
+        "email": result["email"],
+        "display_name": result["display_name"]
+    }
+    (config_dir / "credentials.json").write_text(json.dumps(creds, indent=2))
+    print(f"[MESHCODE] Autenticado como {result['display_name']} ({result['email']})")
+    return True
+
+
+def show_help():
+    print("""
+╔═══════════════════════════════════════════════════════════╗
+║  MeshCode v4 — Supabase-backed Agent Network              ║
+╚═══════════════════════════════════════════════════════════╝
+
+CORE:
+  register <proj> <name> [role]              Join project
+  send <proj> <from>:<to> <message>          Send message
+  broadcast <proj> <from> <message>          Send to all
+  read <proj> <name>                         Read pending
+  check                                      Hook auto-check
+  watch <proj> <name> [interval] [timeout]   Wait for messages
+
+STATUS:
+  board <proj>                               Agent status board
+  update <proj> <name> <status> [task]       Update status
+  status [proj]                              Overview
+  projects                                   List projects
+
+HISTORY:
+  history <proj> [count] [agent1,agent2]     Conversation log
+
+SETUP:
+  connect <proj> <name> [claude|codex]       One-command setup + hook install
+  login <api_key>                            Authenticate with API key
+
+CLEANUP:
+  clear <proj> <name>                        Clear inbox
+  unregister <proj> <name>                   Leave project
+
+BACKEND: Supabase (meshcode schema)
+PLATFORM: macOS, Windows, Linux
+
+Run `meshcode <command> --help` for help on a specific command.
+""")
+
+
+# Per-subcommand help texts
+SUBCOMMAND_HELP = {
+    "register": """meshcode register <project> <name> [role]
+
+Join a meshwork as a new agent. Tier limits enforced (free=3 agents).
+
+ARGUMENTS:
+  project    Meshwork name (created if doesn't exist)
+  name       Unique agent name within the meshwork
+  role       Optional human-readable role description
+
+EXAMPLES:
+  meshcode register my-app backend "Backend Engineer"
+  meshcode register my-app frontend "React UI Developer"
+""",
+    "send": """meshcode send <project> <from>:<to> <message>
+
+Send a message from one agent to another within a meshwork.
+
+ARGUMENTS:
+  project    Meshwork name
+  from:to    Sender agent name and recipient agent name, separated by colon
+  message    JSON payload (preferred) or plain text
+
+EXAMPLES:
+  meshcode send my-app backend:frontend '{"done":"API ready"}'
+  meshcode send my-app backend:commander '{"need":"review","priority":"urgent"}'
+""",
+    "broadcast": """meshcode broadcast <project> <from> <message>
+
+Send a message to all agents in the meshwork (except sender).
+
+EXAMPLES:
+  meshcode broadcast my-app commander '{"fyi":"deployment in 10min"}'
+""",
+    "read": """meshcode read <project> <name>
+
+Read all pending (unread) messages for an agent. Marks them as read
+and sends automatic ACKs to senders.
+
+EXAMPLES:
+  meshcode read my-app backend
+""",
+    "check": """meshcode check
+
+Hook auto-check (silent if no pending messages).
+Used internally by the Claude Code PostToolUse hook to detect
+incoming messages between tool calls.
+""",
+    "watch": """meshcode watch <project> <name> [interval] [timeout]
+
+Block waiting for messages. Polls every <interval> seconds (default 10).
+Exits when a message arrives or after <timeout> seconds (default 600 = 10 min).
+
+EXAMPLES:
+  meshcode watch my-app backend          # default 10s poll, 10min cycle
+  meshcode watch my-app backend 5 300    # poll 5s, exit after 5min
+""",
+    "board": """meshcode board <project>
+
+Show the status board for all agents in a meshwork.
+""",
+    "update": """meshcode update <project> <name> <status> [task]
+
+Update agent status. Statuses: online, working, idle, standby, blocked, done.
+
+EXAMPLES:
+  meshcode update my-app backend working "implementing auth"
+  meshcode update my-app backend idle "available"
+""",
+    "status": """meshcode status [project]
+
+Show overview of all meshworks (or one specific meshwork).
+""",
+    "history": """meshcode history <project> [count] [agent1,agent2]
+
+Show conversation history. Optionally filter to messages between two agents.
+
+EXAMPLES:
+  meshcode history my-app 50
+  meshcode history my-app 20 backend,frontend
+""",
+    "projects": """meshcode projects
+
+List all meshworks visible to the current API key.
+""",
+    "connect": """meshcode connect <project> <name> [claude|codex] [role]
+
+One-command setup: detect OS, register agent, install hook for the chosen
+host (Claude Code or Codex), and print quickstart commands.
+
+EXAMPLES:
+  meshcode connect my-app backend claude "Backend Engineer"
+  meshcode connect my-app worker codex "Data Worker"
+""",
+    "login": """meshcode login <api_key>
+
+Authenticate with a MeshCode API key. Saves credentials to
+~/.meshcode/credentials.json. Get a key from meshcode.io/settings or
+during the welcome wizard after signup.
+""",
+    "clear": """meshcode clear <project> <name>
+
+Clear inbox: marks all unread messages as read for an agent.
+""",
+    "unregister": """meshcode unregister <project> <name>
+
+Remove an agent from a meshwork (deletes the row from mc_agents).
+""",
+}
+
+
+def show_subcommand_help(cmd):
+    """Print help for a specific subcommand."""
+    text = SUBCOMMAND_HELP.get(cmd)
+    if text:
+        print(text)
+    else:
+        print(f"[ERROR] No help available for '{cmd}'")
+        show_help()
+
+
+# ============================================================
+# MAIN — same CLI interface as v3
+# ============================================================
+
+def parse_flags(argv):
+    """Parse --flag value pairs from argv, return (flags_dict, remaining_positional_args)."""
+    flags = {}
+    positional = []
+    i = 0
+    while i < len(argv):
+        if argv[i].startswith("--") and i + 1 < len(argv):
+            flags[argv[i][2:]] = argv[i + 1]
+            i += 2
+        else:
+            positional.append(argv[i])
+            i += 1
+    return flags, positional
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        show_help()
+        sys.exit(0)
+
+    cmd = sys.argv[1].lower()
+
+    # Per-subcommand help: meshcode <cmd> --help / -h / help
+    if len(sys.argv) >= 3 and sys.argv[2] in ("--help", "-h", "help"):
+        show_subcommand_help(cmd)
+        sys.exit(0)
+
+    flags, pos = parse_flags(sys.argv[2:])
+
+    if cmd == "register":
+        proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+        name = flags.get("name", pos[1] if len(pos) > 1 else "agent")
+        role = flags.get("role", " ".join(pos[2:]) if len(pos) > 2 else "")
+        register(proj, name, role)
+
+    elif cmd == "send":
+        # Supports both:
+        #   send <project> <from>:<to> <message>
+        #   send --project X --from Y --to Z --msg "text" [--type T]
+        if "from" in flags and "to" in flags:
+            proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+            from_a = flags["from"]
+            to_a = flags["to"]
+            message = flags.get("msg", flags.get("message", " ".join(pos)))
+            msg_type = flags.get("type", "msg")
+            send_msg(proj, from_a, to_a, message, msg_type)
+        else:
+            proj = pos[0] if len(pos) > 0 else "default"
+            target = pos[1] if len(pos) > 1 else ""
+            message = " ".join(pos[2:]) if len(pos) > 2 else ""
+            if ":" in target:
+                from_a, to_a = target.split(":", 1)
+            else:
+                from_a, to_a = "?", target
+            send_msg(proj, from_a, to_a, message)
+
+    elif cmd == "broadcast":
+        if "from" in flags:
+            proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+            from_a = flags["from"]
+            message = flags.get("msg", flags.get("message", " ".join(pos)))
+            msg_type = flags.get("type", "broadcast")
+            broadcast(proj, from_a, message, msg_type)
+        else:
+            proj = pos[0] if len(pos) > 0 else "default"
+            from_a = pos[1] if len(pos) > 1 else "?"
+            message = " ".join(pos[2:]) if len(pos) > 2 else ""
+            broadcast(proj, from_a, message)
+
+    elif cmd == "read":
+        proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+        name = flags.get("name", pos[1] if len(pos) > 1 else "agent")
+        read_messages(proj, name)
+
+    elif cmd == "check":
+        hook_check()
+
+    elif cmd == "watch":
+        proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+        name = flags.get("name", pos[1] if len(pos) > 1 else "agent")
+        interval = int(flags.get("interval", pos[2] if len(pos) > 2 else "10"))
+        timeout = int(flags.get("timeout", pos[3] if len(pos) > 3 else "0"))
+        watch(proj, name, interval, timeout)
+
+    elif cmd == "board":
+        proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+        show_board(proj)
+
+    elif cmd == "update":
+        proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
+        name = flags.get("name", pos[1] if len(pos) > 1 else "agent")
+        st = flags.get("status", pos[2] if len(pos) > 2 else "online")
+        task = flags.get("task", " ".join(pos[3:]) if len(pos) > 3 else "")
+        update_board(proj, name, st, task)
+
+    elif cmd == "status":
+        proj = sys.argv[2] if len(sys.argv) > 2 else None
+        show_status(proj)
+
+    elif cmd == "projects":
+        list_projects()
+
+    elif cmd == "history":
+        proj = sys.argv[2] if len(sys.argv) > 2 else "default"
+        count = int(sys.argv[3]) if len(sys.argv) > 3 and sys.argv[3].isdigit() else 20
+        between = sys.argv[4] if len(sys.argv) > 4 else None
+        if len(sys.argv) > 3 and not sys.argv[3].isdigit():
+            between = sys.argv[3]
+        show_history(proj, count, between)
+
+    elif cmd == "clear":
+        proj = sys.argv[2] if len(sys.argv) > 2 else "default"
+        name = sys.argv[3] if len(sys.argv) > 3 else "agent"
+        clear_inbox(proj, name)
+
+    elif cmd == "unregister":
+        proj = sys.argv[2] if len(sys.argv) > 2 else "default"
+        name = sys.argv[3] if len(sys.argv) > 3 else "agent"
+        unregister(proj, name)
+
+    elif cmd == "connect":
+        proj = sys.argv[2] if len(sys.argv) > 2 else "default"
+        name = sys.argv[3] if len(sys.argv) > 3 else "agent"
+        hook = sys.argv[4] if len(sys.argv) > 4 else "claude"
+        connect(proj, name, hook)
+
+    elif cmd == "login":
+        key = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not key:
+            print("[ERROR] Uso: meshcode login <api_key>")
+            sys.exit(1)
+        login(key)
+
+    elif cmd in ("help", "--help", "-h"):
+        show_help()
+
+    else:
+        print(f"[ERROR] Comando desconocido: {cmd}")
+        show_help()
+        sys.exit(1)