meshcode 2.11.123__tar.gz → 2.11.124__tar.gz

{meshcode-2.11.123 → meshcode-2.11.124}/PKG-INFO

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

{meshcode-2.11.123 → meshcode-2.11.124}/meshcode/__init__.py

@@ -1,5 +1,5 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.11.123"
+__version__ = "2.11.124"
 
 # Exception hierarchy — eagerly imported (lightweight, no deps)
 from meshcode.exceptions import (  # noqa: F401

{meshcode-2.11.123 → meshcode-2.11.124}/meshcode/meshcode_mcp/realtime.py

@@ -125,24 +125,61 @@ class RealtimeListener:
         self._connected = False
         self._subscription_ok = False
 
+    @staticmethod
+    def _is_auth_rejection(e: Exception) -> bool:
+        """True when the WS handshake was rejected 401/403 — a BAD KEY, not a
+        transient network blip. Task c49096c1 (edge logs: 66x 401/hr): a client
+        with an invalid/rotated apikey retried every ≤60s forever, hammering
+        prod. Auth errors don't heal by retrying."""
+        try:
+            status = getattr(getattr(e, "response", None), "status_code", None)
+            if status is None:
+                status = getattr(e, "status_code", None)  # older websockets
+            return status in (401, 403)
+        except Exception:
+            return False
+
     async def _run(self) -> None:
         """Outer loop: reconnect with exponential backoff on disconnect.
 
-        NEVER gives up — keeps retrying with capped backoff (max 60s).
-        The MCP server must stay alive regardless of Realtime health.
+        Transient errors: NEVER gives up — keeps retrying with capped backoff
+        (max 60s). The MCP server must stay alive regardless of Realtime health.
+        AUTH rejections (401/403) are different (task c49096c1): the key is
+        bad and retrying can't fix it — back off to 5 min immediately and STOP
+        after 5 consecutive auth rejections with one actionable log line.
+        Message delivery survives via the wait-loop poll fallback (mc_wait_poll).
         """
         backoff = 1
         consecutive_failures = 0
+        auth_rejections = 0
         while not self._stop.is_set():
             try:
                 await self._connect_and_listen()
                 backoff = 1  # reset on clean disconnect
                 consecutive_failures = 0
+                auth_rejections = 0
             except asyncio.CancelledError:
                 return
             except Exception as e:
                 consecutive_failures += 1
-                if consecutive_failures % 10 == 0:
+                if self._is_auth_rejection(e):
+                    auth_rejections += 1
+                    if auth_rejections >= 5:
+                        log.error(
+                            "Realtime: 5 consecutive auth rejections (401/403) — the "
+                            "SUPABASE_KEY this agent carries is invalid or rotated. "
+                            "GIVING UP on Realtime (poll fallback stays active). "
+                            "Fix: refresh this workspace's .mcp.json key (re-run "
+                            "`meshcode setup`) and restart the agent."
+                        )
+                        self._connected = False
+                        return
+                    backoff = 300  # bad key: don't hammer prod every 60s
+                    log.warning(
+                        f"Realtime auth rejected ({auth_rejections}/5): {e}; "
+                        f"key likely invalid/rotated — retrying in {backoff}s"
+                    )
+                elif consecutive_failures % 10 == 0:
                     log.error(
                         f"Realtime: {consecutive_failures} consecutive failures — "
                         f"still retrying (backoff={backoff}s). Last error: {e}"

{meshcode-2.11.123 → meshcode-2.11.124}/meshcode/meshcode_mcp/server.py

@@ -6427,6 +6427,102 @@ def meshcode_agent_stop(name: str) -> Dict[str, Any]:
     })
 
 
+# ----------------- ENJAMBRE SWARM HELPER LIFECYCLE (task 227c6a3c) -----------------
+# Spawn → tray loop → self-retire. NO recycle_agent anywhere in this lifecycle
+# (disabled in prod): launch = mc_agent_power_as_agent (G1b parent authz),
+# shutdown = mc_helper_retire → desired_state='stopped' → meshcode_wait
+# must_exit → clean session end; the TTL reaper backstops crashes.
+
+@mcp.tool()
+@with_working_status
+def meshcode_helper_spawn(name: str, role: str = "helper",
+                          swarm_id: Optional[str] = None,
+                          spawned_for_task_id: Optional[str] = None,
+                          ttl_seconds: int = 3600,
+                          headless: Optional[bool] = None) -> Dict[str, Any]:
+    """Spawn an ephemeral HELPER agent into your swarm (you become its parent).
+
+    ENJAMBRE (mig 471 schema + mig 475 wrappers). Server-side, from YOUR
+    agent-scoped api key: registers agent_kind='helper', parent_agent_id=you,
+    auto_retire=true, a TTL, repo/host inherited from you — then powers it on
+    (G1b parent authz + mig 473 concurrent cap compose inside). Budget errors:
+    tier_limit at creation; helper_cap_reached arrives in `power` with the row
+    created but stopped (stagger and re-power, or retire it). Helpers cannot
+    spawn helpers (helper_chain_forbidden, v1).
+
+    The helper works its swarm tray via meshcode_tray_claim and self-retires
+    when the tray drains — you never stop it manually (meshcode_agent_stop is
+    the manual override; NEVER recycle, it's disabled).
+
+    Args:
+        name: helper agent name (unique in the meshwork; name_taken on collision).
+        role: short role description shown on the dashboard.
+        swarm_id: tray to join; omit to mint a fresh tray id for a new swarm.
+        spawned_for_task_id: optional umbrella task this helper serves.
+        ttl_seconds: hard lifetime cap (60..86400); reaper retires it past this.
+        headless: omit for the server default; explicit True/False forces the
+            window mode via a separate power-on call.
+    """
+    from . import swarm as _swarm
+    return _swarm.spawn_helper(_get_api_key(), _PROJECT_ID, name, role=role,
+                               swarm_id=swarm_id,
+                               spawned_for_task_id=spawned_for_task_id,
+                               ttl_seconds=ttl_seconds, headless=headless)
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_tray_claim(lease_seconds: int = 900,
+                        swarm_id: Optional[str] = None) -> Dict[str, Any]:
+    """HELPER loop step: atomically claim the next runnable task from your
+    swarm tray (work-stealing, DAG-gated, priority-ordered).
+
+    ENJAMBRE (mig 471 + 475). Interpret the result:
+      - claimed=true  → work the returned task NOW, then meshcode_task_complete.
+        Re-claim after completing — keep draining.
+      - claimed=false, drained=true  → tray is empty and final: call
+        meshcode_helper_retire, then meshcode_wait (returns must_exit → end
+        session). Do NOT idle.
+      - claimed=false, drained=false → tasks exist but are DAG-blocked: wait
+        briefly and claim again.
+
+    Args:
+        lease_seconds: claim lease (60..86400); an expired lease re-opens the task.
+        swarm_id: override tray; omit to use your own agent row's swarm
+            (helpers get theirs stamped at spawn).
+    """
+    from . import swarm as _swarm
+    sid = swarm_id or _swarm.own_swarm_id(_PROJECT_ID, AGENT_NAME)
+    if not sid:
+        return {"ok": False, "error": "no swarm: your agent row has no swarm_id "
+                                      "and none was given — are you a helper?"}
+    return _swarm.tray_claim(_get_api_key(), _PROJECT_ID, swarm_id=sid,
+                             lease_seconds=lease_seconds)
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_helper_retire(reason: str = "tray_drained") -> Dict[str, Any]:
+    """HELPER self-retire — the ONLY sanctioned helper shutdown (auto-off,
+    ZERO orphans). Self-only by construction; persistent agents get
+    not_a_helper, auto_retire=false rows get auto_retire_disabled.
+
+    ENJAMBRE (mig 471 + 475). Flips your desired_state='stopped' +
+    status='sleeping' server-side: hostd will not respawn you and your next
+    meshcode_wait returns must_exit=True. Sequence: finish/complete the current
+    task → meshcode_helper_retire → meshcode_wait → exit on must_exit.
+
+    Args:
+        reason: telemetry tag (tray_drained | ttl_expired | parent_request | ...).
+    """
+    from . import swarm as _swarm
+    result = _swarm.retire_self(_get_api_key(), _PROJECT_ID, reason=reason)
+    if isinstance(result, dict) and result.get("ok"):
+        result["next_step"] = ("retired — now call meshcode_wait(); it returns "
+                               "must_exit=True and you end the session")
+    return result
+
+
 @mcp.tool()
 @with_working_status
 def meshcode_recycle_agent(name: str, visible: bool = False) -> Dict[str, Any]:

meshcode-2.11.124/meshcode/meshcode_mcp/swarm.py

@@ -0,0 +1,292 @@
+"""ENJAMBRE — swarm helper lifecycle SDK (task 227c6a3c, branch enjambre/sdk-helpers).
+
+Implements the launcher/SDK side of the swarm helper lifecycle on top of the
+mig 471 schema (mc_agents.agent_kind/parent_agent_id/swarm_id/spawned_for_task_id/
+auto_retire/ttl_expires_at + mc_task_claim_from_tray + mc_helper_retire):
+
+  1. SPAWN   — parent calls mc_helper_spawn_as_agent: server derives parentage
+               from the caller's agent-scoped api key (never client-claimed),
+               INSERT-only helper row inheriting repo_path/host from the parent,
+               tier row-budget at creation, and (p_power_on) composes power-on
+               through mc_agent_power_as_agent — parent authz (mig 471 G1b) +
+               concurrent running cap (mig 473) live in exactly one place.
+  2. LOOP    — helper claims work from its swarm tray (claim_from_tray):
+               claimed → work + mc_task_complete; drained → retire + exit.
+               Not-claimed-not-drained means DAG-blocked deps are pending:
+               poll again after a short sleep.
+  3. SHUTDOWN — NO recycle_agent (DISABLED in prod). mc_helper_retire flips
+               desired_state='stopped' + status='sleeping'; the agent's next
+               meshcode_wait returns must_exit=True and the session ends. hostd
+               never respawns desired_state='stopped', and the service-side
+               reaper (mc_swarm_reap_expired_helpers) + ttl_expires_at backstop
+               guarantee ZERO orphan helpers even on crash.
+
+DATA CONTRACT — FROZEN by database@mesh-core (msg 34121217), LIVE in prod as
+mig 475 (commander msg 50b4ab8d; authored as 20260610_474_* on branch
+enjambre/g3-runtime, renumbered at apply):
+
+  public.mc_task_claim_from_tray_as_agent(p_api_key text, p_project_id uuid,
+      p_swarm_id uuid, p_lease_seconds int DEFAULT 900) -> jsonb
+      {ok, claimed:true, task_id, title, description, priority, parent_task_id,
+       lease_expires_at} | {ok:true, claimed:false, drained:bool}
+      p_swarm_id is REQUIRED (claims never cross trays); the SDK resolves the
+      caller's own mc_agents.swarm_id when not given explicitly.
+
+  public.mc_helper_retire_as_agent(p_api_key text, p_project_id uuid,
+      p_reason text DEFAULT 'tray_drained') -> {ok, retired, reason}
+      Self-only by construction. Errors: auth_failed | agent_key_required |
+      wrong_scope | agent_not_found | not_a_helper | auto_retire_disabled.
+
+  public.mc_helper_spawn_as_agent(p_api_key text, p_project_id uuid,
+      p_name text, p_swarm_id uuid, p_spawned_for_task_id uuid DEFAULT NULL,
+      p_role text DEFAULT 'helper', p_auto_retire bool DEFAULT true,
+      p_ttl_seconds int DEFAULT 3600, p_power_on bool DEFAULT true) -> jsonb
+      {ok, agent_id, name, agent_kind, parent_agent_id, swarm_id,
+       spawned_for_task_id, auto_retire, ttl_expires_at, power}
+      Errors: bad_name | bad_swarm | auth_failed | agent_key_required |
+      wrong_scope | agent_not_found | helper_chain_forbidden | tier_limit |
+      name_taken; a concurrent-cap refusal (helper_cap_reached) arrives inside
+      `power` with the row already created but stopped (retire or re-power).
+"""
+
+import logging
+import time
+import uuid as _uuid
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote as _quote
+
+from . import backend as be
+
+log = logging.getLogger("meshcode.swarm")
+
+# Frozen contract names (mig 475 live in prod).
+RPC_HELPER_SPAWN = "mc_helper_spawn_as_agent"
+RPC_TRAY_CLAIM = "mc_task_claim_from_tray_as_agent"
+RPC_HELPER_RETIRE = "mc_helper_retire_as_agent"
+RPC_AGENT_POWER = "mc_agent_power_as_agent"   # mig 416 + 471 G1b + 473 cap
+RPC_TASK_COMPLETE = "mc_task_complete"        # live, agent-callable (rpc_allowlist)
+
+DEFAULT_TTL_SECONDS = 3600
+DEFAULT_LEASE_SECONDS = 900
+DEFAULT_POLL_SECONDS = 15.0
+MAX_CONSECUTIVE_ERRORS = 5
+
+
+def _err(result: Any) -> Optional[str]:
+    """Normalize a backend result to an error string, or None if it's ok."""
+    if result is None:
+        return "empty response"
+    if be.is_error(result):
+        return be.get_error_message(result) or "rpc error"
+    if isinstance(result, dict) and result.get("ok") is False:
+        return result.get("error") or result.get("error_code") or "rpc refused"
+    return None
+
+
+def own_swarm_id(project_id: str, agent_name: str) -> Optional[str]:
+    """Resolve the caller's own mc_agents.swarm_id (helpers get theirs stamped
+    at spawn). Claims are tray-scoped — p_swarm_id is required by contract."""
+    rows = be.sb_select(
+        "mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{_quote(agent_name)}&select=swarm_id",
+        limit=1)
+    if rows and rows[0].get("swarm_id"):
+        return rows[0]["swarm_id"]
+    return None
+
+
+def spawn_helper(api_key: str, project_id: str, name: str, *,
+                 role: str = "helper",
+                 swarm_id: Optional[str] = None,
+                 spawned_for_task_id: Optional[str] = None,
+                 ttl_seconds: int = DEFAULT_TTL_SECONDS,
+                 launch: bool = True,
+                 headless: Optional[bool] = None) -> Dict[str, Any]:
+    """Spawn an ephemeral helper. Parent = caller (server-derived, W2).
+
+    swarm_id=None mints a fresh tray id client-side (the contract requires it
+    NOT NULL — helper invariant). headless=None lets the server's power-on
+    default apply (single RPC); an explicit True/False does spawn with
+    p_power_on=false and a separate mc_agent_power_as_agent call carrying
+    p_headless. The helper's workspace materializes via `meshcode run`'s
+    auto-setup when hostd spawns it (W5: row inherits repo_path/host).
+    """
+    v_swarm = swarm_id or str(_uuid.uuid4())
+    single_rpc_power = launch and headless is None
+
+    reg = be.sb_rpc(RPC_HELPER_SPAWN, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_name": name,
+        "p_swarm_id": v_swarm,
+        "p_spawned_for_task_id": spawned_for_task_id,
+        "p_role": role,
+        "p_auto_retire": True,
+        "p_ttl_seconds": int(ttl_seconds),
+        "p_power_on": bool(single_rpc_power),
+    })
+    err = _err(reg)
+    if err:
+        return {"ok": False, "stage": "register", "error": err,
+                **({"error_code": reg.get("error_code")} if isinstance(reg, dict) and reg.get("error_code") else {})}
+
+    out: Dict[str, Any] = {"ok": True, "helper": name, "launched": bool(launch)}
+    if isinstance(reg, dict):
+        out.update({k: reg[k] for k in
+                    ("agent_id", "swarm_id", "parent_agent_id", "ttl_expires_at")
+                    if k in reg})
+        power = reg.get("power")
+    else:
+        power = None
+
+    if launch and not single_rpc_power:
+        power = be.sb_rpc(RPC_AGENT_POWER, {
+            "p_api_key": api_key,
+            "p_project_id": project_id,
+            "p_agent": name,
+            "p_state": "running",
+            "p_headless": bool(headless),
+        })
+
+    if launch:
+        perr = _err(power)
+        if perr:
+            # Row created but not running (e.g. helper_cap_reached, mig 473).
+            # Caller may stagger/retire and re-power; TTL reaper backstops.
+            return {**out, "ok": False, "stage": "power_on", "error": perr,
+                    "power": power}
+        if isinstance(power, dict):
+            out["powered_by"] = power.get("powered_by")
+            out["no_host"] = power.get("no_host")
+    return out
+
+
+def tray_claim(api_key: str, project_id: str, *,
+               swarm_id: str,
+               lease_seconds: int = DEFAULT_LEASE_SECONDS) -> Dict[str, Any]:
+    """Claim the next runnable task from the swarm tray (atomic, work-stealing,
+    DAG-gated, priority-ordered). p_swarm_id is contract-required; use
+    own_swarm_id() to resolve yours.
+
+    Returns the raw contract shape: {ok, claimed, task...} or
+    {ok, claimed:false, drained:bool}. drained=false with claimed=false means
+    DAG-blocked work is still pending — poll again, do NOT retire.
+    """
+    if not swarm_id:
+        return {"ok": False, "error": "swarm_id required (no swarm on your agent row?)"}
+    result = be.sb_rpc(RPC_TRAY_CLAIM, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_swarm_id": swarm_id,
+        "p_lease_seconds": int(lease_seconds),
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}
+
+
+def retire_self(api_key: str, project_id: str, *,
+                reason: str = "tray_drained") -> Dict[str, Any]:
+    """Self-retire (helpers only — self-only by construction). Flips
+    desired_state='stopped' server-side; the next meshcode_wait returns
+    must_exit=True and the session ends clean. This is the ONLY sanctioned
+    helper shutdown — never recycle_agent (disabled)."""
+    result = be.sb_rpc(RPC_HELPER_RETIRE, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_reason": reason,
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}
+
+
+def complete_task(api_key: str, task_id: str, summary: str = "") -> Dict[str, Any]:
+    """Thin wrapper over the live mc_task_complete RPC."""
+    result = be.sb_rpc(RPC_TASK_COMPLETE, {
+        "p_api_key": api_key,
+        "p_task_id": task_id,
+        "p_summary": summary,
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": True}
+
+
+def helper_loop(api_key: str, project_id: str, swarm_id: str,
+                work_fn: Callable[[Dict[str, Any]], str], *,
+                lease_seconds: int = DEFAULT_LEASE_SECONDS,
+                poll_seconds: float = DEFAULT_POLL_SECONDS,
+                ttl_deadline: Optional[float] = None,
+                max_tasks: Optional[int] = None,
+                sleep_fn: Callable[[float], None] = time.sleep,
+                clock: Callable[[], float] = time.monotonic) -> Dict[str, Any]:
+    """Programmatic helper loop: claim → work → complete; drained → retire.
+
+    For scripted/headless helpers (harness, batch runners). Interactive Claude
+    helpers run the same protocol through the meshcode_tray_claim /
+    meshcode_helper_retire MCP tools instead.
+
+    Owner's non-negotiable guard (ZERO orphans): EVERY exit path retires the
+    helper — drained, ttl_expired, error budget exhausted, or task cap. work_fn
+    exceptions do NOT kill the loop (the claim lease expires server-side and the
+    reaper re-opens the task); only the consecutive-error budget can.
+
+    work_fn receives the claim payload and returns a completion summary string.
+    """
+    done = 0
+    consecutive_errors = 0
+    retired_reason: Optional[str] = None
+
+    while True:
+        if ttl_deadline is not None and clock() >= ttl_deadline:
+            retired_reason = "ttl_expired"
+            break
+        if max_tasks is not None and done >= max_tasks:
+            retired_reason = "max_tasks"
+            break
+
+        claim = tray_claim(api_key, project_id, swarm_id=swarm_id,
+                           lease_seconds=lease_seconds)
+        if not claim.get("ok"):
+            consecutive_errors += 1
+            log.warning("tray_claim error (%d/%d): %s",
+                        consecutive_errors, MAX_CONSECUTIVE_ERRORS, claim.get("error"))
+            if consecutive_errors >= MAX_CONSECUTIVE_ERRORS:
+                retired_reason = "claim_errors"
+                break
+            sleep_fn(min(poll_seconds * consecutive_errors, 60.0))
+            continue
+        consecutive_errors = 0
+
+        if claim.get("claimed"):
+            task_id = claim.get("task_id")
+            try:
+                summary = work_fn(claim) or ""
+            except Exception as e:  # lease expiry + reaper recover the task
+                log.warning("work_fn failed on task %s: %s", task_id, e)
+                continue
+            comp = complete_task(api_key, task_id, summary)
+            if comp.get("ok") is not False:
+                done += 1
+            else:
+                log.warning("task_complete failed on %s: %s", task_id, comp.get("error"))
+            continue
+
+        if claim.get("drained"):
+            retired_reason = "tray_drained"
+            break
+
+        # Not claimed, not drained: DAG-blocked deps still pending. Poll.
+        sleep_fn(poll_seconds)
+
+    retire = retire_self(api_key, project_id, reason=retired_reason or "tray_drained")
+    return {
+        "ok": True,
+        "tasks_done": done,
+        "retired_reason": retired_reason,
+        "retire_result": retire,
+    }

meshcode-2.11.124/meshcode/meshcode_mcp/test_swarm.py

@@ -0,0 +1,279 @@
+"""Offline unit tests for the ENJAMBRE helper lifecycle SDK (swarm.py).
+
+Stdlib only (unittest + mock), zero network: be.sb_rpc / be.sb_select are
+patched with scripted fakes. Contract under test = the FROZEN mig 475
+wrappers (database@mesh-core msg 34121217). Covers the owner's non-negotiable
+guard — EVERY helper_loop exit path retires the helper (zero orphans) — plus
+budget surfacing (tier_limit at register, helper_cap_reached in power), drain
+semantics, DAG-blocked polling, ttl expiry, error budget, and the no-recycle
+rule (no code path may ever call mc_recycle*).
+"""
+import unittest
+from unittest import mock
+
+from . import swarm
+
+PROJ = "proj-1"
+
+
+class _FakeRpc:
+    """Scripted sb_rpc fake: records calls, answers per-function queues."""
+
+    def __init__(self):
+        self.calls = []          # (fn_name, params)
+        self.queues = {}         # fn_name -> list of responses (popped FIFO)
+        self.default = {"ok": True}
+
+    def script(self, fn_name, *responses):
+        self.queues.setdefault(fn_name, []).extend(responses)
+
+    def __call__(self, fn_name, params, **kw):
+        self.calls.append((fn_name, params))
+        q = self.queues.get(fn_name)
+        if q:
+            return q.pop(0)
+        return dict(self.default)
+
+    def called_fns(self):
+        return [fn for fn, _ in self.calls]
+
+
+class SwarmTestCase(unittest.TestCase):
+    def setUp(self):
+        self.rpc = _FakeRpc()
+        patcher = mock.patch.object(swarm.be, "sb_rpc", self.rpc)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+
+    def assert_no_recycle(self):
+        """recycle_agent is DISABLED in prod — the helper lifecycle must never
+        touch any mc_recycle* RPC on any path."""
+        for fn in self.rpc.called_fns():
+            self.assertNotIn("recycle", fn, f"forbidden recycle RPC called: {fn}")
+
+
+class SpawnTests(SwarmTestCase):
+    def test_spawn_single_rpc_composes_power_on(self):
+        """Default (headless unset): ONE RPC — server composes power-on."""
+        self.rpc.script(swarm.RPC_HELPER_SPAWN,
+                        {"ok": True, "agent_id": "h-1", "name": "helper-1",
+                         "swarm_id": "s-1", "parent_agent_id": "p-1",
+                         "ttl_expires_at": "2026-06-10T01:00:00Z",
+                         "power": {"ok": True, "powered_by": "parent:qa",
+                                   "no_host": False}})
+
+        out = swarm.spawn_helper("KEY", PROJ, "helper-1",
+                                 swarm_id="s-1", spawned_for_task_id="t-9",
+                                 ttl_seconds=120)
+
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["agent_id"], "h-1")
+        self.assertEqual(out["swarm_id"], "s-1")
+        self.assertEqual(out["powered_by"], "parent:qa")
+        self.assertEqual(self.rpc.called_fns(), [swarm.RPC_HELPER_SPAWN])
+
+        _, params = self.rpc.calls[0]
+        self.assertEqual(params["p_project_id"], PROJ)
+        self.assertEqual(params["p_swarm_id"], "s-1")
+        self.assertEqual(params["p_spawned_for_task_id"], "t-9")
+        self.assertEqual(params["p_ttl_seconds"], 120)
+        self.assertTrue(params["p_auto_retire"])
+        self.assertTrue(params["p_power_on"])
+        self.assert_no_recycle()
+
+    def test_spawn_mints_swarm_id_when_omitted(self):
+        """Contract: p_swarm_id NOT NULL (bad_swarm otherwise) — SDK mints."""
+        self.rpc.script(swarm.RPC_HELPER_SPAWN, {"ok": True, "agent_id": "h-1"})
+        swarm.spawn_helper("KEY", PROJ, "helper-1")
+        _, params = self.rpc.calls[0]
+        self.assertTrue(params["p_swarm_id"])  # a freshly minted uuid
+
+    def test_spawn_explicit_headless_uses_two_rpcs(self):
+        self.rpc.script(swarm.RPC_HELPER_SPAWN, {"ok": True, "agent_id": "h-1"})
+        self.rpc.script(swarm.RPC_AGENT_POWER,
+                        {"ok": True, "powered_by": "parent:qa"})
+        out = swarm.spawn_helper("KEY", PROJ, "helper-1", headless=True)
+        self.assertTrue(out["ok"])
+        _, spawn_params = self.rpc.calls[0]
+        self.assertFalse(spawn_params["p_power_on"])
+        fn, power_params = self.rpc.calls[1]
+        self.assertEqual(fn, swarm.RPC_AGENT_POWER)
+        self.assertEqual(power_params["p_state"], "running")
+        self.assertTrue(power_params["p_headless"])
+
+    def test_spawn_tier_limit_surfaces_register_stage(self):
+        self.rpc.script(swarm.RPC_HELPER_SPAWN,
+                        {"ok": False, "error_code": "tier_limit",
+                         "error": "Agent limit reached for free plan (3/3)"})
+        out = swarm.spawn_helper("KEY", PROJ, "helper-1")
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["stage"], "register")
+        self.assertEqual(out["error_code"], "tier_limit")
+        self.assertEqual(self.rpc.called_fns(), [swarm.RPC_HELPER_SPAWN])
+
+    def test_spawn_helper_cap_in_power_reports_power_on_stage(self):
+        """mig 473 concurrent cap: row created, power refused — caller can
+        stagger/re-power; the TTL reaper backstops abandonment."""
+        self.rpc.script(swarm.RPC_HELPER_SPAWN,
+                        {"ok": True, "agent_id": "h-1", "swarm_id": "s-1",
+                         "power": {"ok": False, "error_code": "helper_cap_reached",
+                                   "error": "too many running helpers"}})
+        out = swarm.spawn_helper("KEY", PROJ, "helper-1", swarm_id="s-1")
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["stage"], "power_on")
+        self.assertEqual(out["agent_id"], "h-1")
+        self.assertIn("helpers", out["error"])
+
+    def test_spawn_launch_false_registers_only(self):
+        self.rpc.script(swarm.RPC_HELPER_SPAWN, {"ok": True, "agent_id": "h-1"})
+        out = swarm.spawn_helper("KEY", PROJ, "helper-1", launch=False)
+        self.assertTrue(out["ok"])
+        self.assertFalse(out["launched"])
+        _, params = self.rpc.calls[0]
+        self.assertFalse(params["p_power_on"])
+        self.assertEqual(self.rpc.called_fns(), [swarm.RPC_HELPER_SPAWN])
+
+
+class TrayClaimTests(SwarmTestCase):
+    def test_claim_passes_full_contract_params(self):
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        {"ok": True, "claimed": True, "task_id": "t-1"})
+        out = swarm.tray_claim("KEY", PROJ, swarm_id="s-1", lease_seconds=300)
+        self.assertTrue(out["claimed"])
+        _, params = self.rpc.calls[0]
+        self.assertEqual(params["p_project_id"], PROJ)
+        self.assertEqual(params["p_swarm_id"], "s-1")
+        self.assertEqual(params["p_lease_seconds"], 300)
+
+    def test_claim_requires_swarm_id(self):
+        out = swarm.tray_claim("KEY", PROJ, swarm_id=None)
+        self.assertFalse(out["ok"])
+        self.assertIn("swarm_id required", out["error"])
+        self.assertEqual(self.rpc.calls, [])  # never hit the wire
+
+    def test_claim_error_normalized(self):
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        swarm.be._make_error("boom", code="500", source="rpc"))
+        out = swarm.tray_claim("KEY", PROJ, swarm_id="s-1")
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["error"], "boom")
+
+
+class OwnSwarmTests(unittest.TestCase):
+    def test_own_swarm_id_reads_own_row(self):
+        with mock.patch.object(swarm.be, "sb_select",
+                               return_value=[{"swarm_id": "s-9"}]) as sel:
+            self.assertEqual(swarm.own_swarm_id(PROJ, "helper-1"), "s-9")
+        filters = sel.call_args[0][1]
+        self.assertIn(f"project_id=eq.{PROJ}", filters)
+        self.assertIn("name=eq.helper-1", filters)
+
+    def test_own_swarm_id_none_when_unset(self):
+        with mock.patch.object(swarm.be, "sb_select",
+                               return_value=[{"swarm_id": None}]):
+            self.assertIsNone(swarm.own_swarm_id(PROJ, "qa"))
+
+
+class RetireTests(SwarmTestCase):
+    def test_retire_ok(self):
+        self.rpc.script(swarm.RPC_HELPER_RETIRE,
+                        {"ok": True, "retired": "helper-1", "reason": "tray_drained"})
+        out = swarm.retire_self("KEY", PROJ)
+        self.assertTrue(out["ok"])
+        _, params = self.rpc.calls[0]
+        self.assertEqual(params["p_project_id"], PROJ)
+        self.assertEqual(params["p_reason"], "tray_drained")
+
+    def test_retire_not_a_helper_refused(self):
+        self.rpc.script(swarm.RPC_HELPER_RETIRE,
+                        {"ok": False, "error": "not_a_helper"})
+        out = swarm.retire_self("KEY", PROJ)
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["error"], "not_a_helper")
+
+
+class HelperLoopTests(SwarmTestCase):
+    """The lifecycle core: claim → work → complete; drained → retire + exit."""
+
+    def setUp(self):
+        super().setUp()
+        self.sleeps = []
+        self.sleep = self.sleeps.append   # no real sleeping in tests
+
+    def _loop(self, work_fn, **kw):
+        return swarm.helper_loop("KEY", PROJ, "s-1", work_fn,
+                                 sleep_fn=self.sleep, **kw)
+
+    def test_drain_after_two_tasks_retires(self):
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        {"ok": True, "claimed": True, "task_id": "t-1", "title": "a"},
+                        {"ok": True, "claimed": True, "task_id": "t-2", "title": "b"},
+                        {"ok": True, "claimed": False, "drained": True})
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True, "retired": "h"})
+
+        worked = []
+        out = self._loop(lambda t: worked.append(t["task_id"]) or "done")
+
+        self.assertEqual(worked, ["t-1", "t-2"])
+        self.assertEqual(out["tasks_done"], 2)
+        self.assertEqual(out["retired_reason"], "tray_drained")
+        # every claimed task was completed BEFORE retiring
+        fns = self.rpc.called_fns()
+        self.assertEqual(fns.count(swarm.RPC_TASK_COMPLETE), 2)
+        self.assertEqual(fns[-1], swarm.RPC_HELPER_RETIRE)
+        self.assert_no_recycle()
+
+    def test_dag_blocked_polls_then_drains(self):
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        {"ok": True, "claimed": False, "drained": False},  # blocked deps
+                        {"ok": True, "claimed": False, "drained": True})
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True})
+        out = self._loop(lambda t: "")
+        self.assertEqual(out["tasks_done"], 0)
+        self.assertEqual(out["retired_reason"], "tray_drained")
+        self.assertEqual(len(self.sleeps), 1)  # polled once while blocked
+
+    def test_work_fn_exception_does_not_orphan(self):
+        """work_fn blowing up must neither complete the task nor kill the loop:
+        the lease expires server-side; the loop keeps draining and retires."""
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        {"ok": True, "claimed": True, "task_id": "t-bad"},
+                        {"ok": True, "claimed": False, "drained": True})
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True})
+
+        def explode(_t):
+            raise RuntimeError("kaput")
+
+        out = self._loop(explode)
+        self.assertEqual(out["tasks_done"], 0)
+        self.assertEqual(out["retired_reason"], "tray_drained")
+        self.assertNotIn(swarm.RPC_TASK_COMPLETE, self.rpc.called_fns())
+        self.assertIn(swarm.RPC_HELPER_RETIRE, self.rpc.called_fns())
+
+    def test_claim_error_budget_exhaustion_still_retires(self):
+        for _ in range(swarm.MAX_CONSECUTIVE_ERRORS):
+            self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                            swarm.be._make_error("net down", code="0", source="network"))
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True})
+        out = self._loop(lambda t: "")
+        self.assertEqual(out["retired_reason"], "claim_errors")
+        self.assertEqual(self.rpc.called_fns()[-1], swarm.RPC_HELPER_RETIRE)
+
+    def test_ttl_deadline_retires_before_claiming(self):
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True})
+        out = self._loop(lambda t: "", ttl_deadline=100.0, clock=lambda: 200.0)
+        self.assertEqual(out["retired_reason"], "ttl_expired")
+        self.assertEqual(self.rpc.called_fns(), [swarm.RPC_HELPER_RETIRE])
+
+    def test_max_tasks_cap_retires(self):
+        self.rpc.script(swarm.RPC_TRAY_CLAIM,
+                        {"ok": True, "claimed": True, "task_id": "t-1"})
+        self.rpc.script(swarm.RPC_HELPER_RETIRE, {"ok": True})
+        out = self._loop(lambda t: "ok", max_tasks=1)
+        self.assertEqual(out["tasks_done"], 1)
+        self.assertEqual(out["retired_reason"], "max_tasks")
+        self.assert_no_recycle()
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

{meshcode-2.11.123 → meshcode-2.11.124}/meshcode.egg-info/PKG-INFO

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

{meshcode-2.11.123 → meshcode-2.11.124}/meshcode.egg-info/SOURCES.txt

@@ -45,12 +45,14 @@ meshcode/meshcode_mcp/backend.py
 meshcode/meshcode_mcp/realtime.py
 meshcode/meshcode_mcp/server.py
 meshcode/meshcode_mcp/sleep_signals.py
+meshcode/meshcode_mcp/swarm.py
 meshcode/meshcode_mcp/test_backend.py
 meshcode/meshcode_mcp/test_boot_timing.py
 meshcode/meshcode_mcp/test_install_guard.py
 meshcode/meshcode_mcp/test_prefs_claude_version.py
 meshcode/meshcode_mcp/test_realtime.py
 meshcode/meshcode_mcp/test_server_wrapper.py
+meshcode/meshcode_mcp/test_swarm.py
 meshcode/scripts/check_secrets.py
 meshcode/scripts/race_rate_harness.py
 tests/test_auto_update_hardening.py

{meshcode-2.11.123 → meshcode-2.11.124}/pyproject.toml

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