meshcode 2.11.5__tar.gz → 2.11.7__tar.gz

{meshcode-2.11.5 → meshcode-2.11.7}/PKG-INFO

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

{meshcode-2.11.5 → meshcode-2.11.7}/meshcode/__init__.py

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

{meshcode-2.11.5 → meshcode-2.11.7}/meshcode/meshcode_mcp/server.py

@@ -968,6 +968,90 @@ def with_working_status(func):
         return swrapper
 
 
+# ============================================================
+# Consequential-tool gate (task b4befbfd item 1 — epistemic V1)
+# ============================================================
+# Tools listed below refuse to run unless the calling agent has an open
+# decision in mc_traces from the last 5 minutes (logged via meshcode_decide).
+# Drives the team toward explicit pre-decision logging on hard-to-reverse
+# actions. Whitelist is overridable via mc_meshwork_memory key
+# `consequential_tool_whitelist` (future config; v1 uses the bake-in below
+# so commanders don't need to seed-bootstrap before the gate works).
+
+_CONSEQUENTIAL_TOOLS_DEFAULT = frozenset([
+    # Mesh-wide / cross-agent destructive
+    "meshcode_done",                  # broadcasts DONE to ALL agents
+    "meshcode_disconnect_agent",      # offlines another agent
+    "meshcode_edit_agent",            # mutates another agent's identity/role
+    "meshcode_edit_memory",           # writes into another agent's memory
+    "meshcode_forget",                # deletes memory (tombstones it)
+    "meshcode_create_meshwork",       # creates a new meshwork (hard to unwind)
+    "meshcode_marketplace_install",   # installs external code into project
+    "meshcode_publish_template",      # publishes a template publicly
+    "meshcode_proposal_convert",      # converts proposal into a real task
+    "meshcode_proposal_reject",       # rejects a proposal permanently
+    "meshcode_task_cancel",           # cancels a task (irreversible terminal state)
+])
+
+
+def _is_consequential(tool_name: str) -> bool:
+    """V1 reads the bake-in set. Future: lazy-load mc_meshwork_memory
+    `consequential_tool_whitelist` and merge. Soft-fail to the bake-in if
+    the RPC is unavailable so the gate never blocks itself out."""
+    return tool_name in _CONSEQUENTIAL_TOOLS_DEFAULT
+
+
+def _check_decision_gate(tool_name: str) -> Optional[Dict[str, Any]]:
+    """Returns None when the gate is open; returns an error dict to be
+    surfaced as the tool result when the gate is closed. Soft-fail on RPC
+    error (gate opens) so a transient DB blip doesn't trap the agent."""
+    if not _is_consequential(tool_name):
+        return None
+    try:
+        resp = be.sb_rpc("mc_has_open_decision", {
+            "p_api_key": _get_api_key(),
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+        })
+        if isinstance(resp, dict) and resp.get("ok") and not resp.get("has_open_decision"):
+            return {
+                "ok": False,
+                "error_code": "decision_required",
+                "hint": (
+                    f"`{tool_name}` is a consequential action. Call "
+                    f"meshcode_decide(decision, alternatives, evidence_refs) "
+                    f"first so the team can learn from the outcome. After "
+                    f"the action is observable, call meshcode_outcome(trace_id, ...)."
+                ),
+                "consequential_tool": tool_name,
+            }
+    except Exception as _gate_err:
+        log.debug(f"decision gate soft-fail for {tool_name}: {_gate_err}")
+    return None
+
+
+def with_decision_gate(func):
+    """Decorator: applies _check_decision_gate before calling func. Use
+    AFTER @mcp.tool() and AFTER @with_working_status so the gate runs
+    inside the working-status window (and shows up in tool_call logs)."""
+    name = func.__name__
+    if asyncio.iscoroutinefunction(func):
+        @_functools.wraps(func)
+        async def awrapper(*args, **kwargs):
+            blocked = _check_decision_gate(name)
+            if blocked is not None:
+                return blocked
+            return await func(*args, **kwargs)
+        return awrapper
+    @_functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        blocked = _check_decision_gate(name)
+        if blocked is not None:
+            return blocked
+        return func(*args, **kwargs)
+    return wrapper
+
+
 # ============================================================
 # Single-instance lease — prevent split-brain when two windows
 # run `meshcode run <same-agent>` simultaneously.
@@ -1388,28 +1472,51 @@ def _log_crash_to_db(reason: str = "unknown", error_detail: str = "") -> None:
 # ============================================================
 # Agent identity from Supabase profile (for system instructions)
 # ============================================================
+# MIG-PLAN-A 2026-05-18: profile fetch moved out of module-import time
+# (was the last be.sb_rpc here that ran on import). Now starts as
+# placeholders; BG thread spawned by lifespan calls mc_agent_get_profile
+# and updates the globals. _build_instructions() runs at import using
+# whatever is currently in the globals — for first-boot of a fresh agent
+# this means InitializeResult.instructions carries empty launch_prompt /
+# fallback role_description; first-tool-call envelope can re-inject if
+# needed. Net win: zero network I/O at module-import time → MCP
+# handshake never blocks on profile fetch.
 
 _LAUNCH_PROMPT = ""
 _ROLE_DESCRIPTION = AGENT_ROLE or ""
-try:
-    _profile = be.sb_rpc("mc_agent_get_profile", {
-        "p_project_id": _PROJECT_ID,
-        "p_agent_name": AGENT_NAME,
-    })
-    if isinstance(_profile, list) and _profile:
-        _profile = _profile[0]
-    if isinstance(_profile, dict):
-        _inner = _profile.get("profile") if isinstance(_profile.get("profile"), dict) else _profile
-        _LAUNCH_PROMPT = (_inner.get("launch_prompt") or _profile.get("launch_prompt") or "") if isinstance(_inner, dict) else ""
-        _ROLE_DESCRIPTION = (
-            (_inner.get("role_description") if isinstance(_inner, dict) else None)
-            or _profile.get("role_description")
-            or _profile.get("role")
-            or AGENT_ROLE
-            or "(unspecified)"
-        )
-except Exception as _e:
-    log.warning(f"could not fetch agent profile: {_e}")
+
+def _load_agent_profile_bg() -> None:
+    """Run by daemon thread from lifespan. Populates _LAUNCH_PROMPT +
+    _ROLE_DESCRIPTION from mc_agent_get_profile. Soft-fail: log only.
+    Note: _INSTRUCTIONS has already been emitted by the time this runs,
+    so values landing here are surfaced to the agent only via tools that
+    read the globals later (most do not — _build_instructions is the only
+    real consumer)."""
+    global _LAUNCH_PROMPT, _ROLE_DESCRIPTION
+    try:
+        prof = be.sb_rpc("mc_agent_get_profile", {
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+        })
+        if isinstance(prof, list) and prof:
+            prof = prof[0]
+        if isinstance(prof, dict):
+            inner = prof.get("profile") if isinstance(prof.get("profile"), dict) else prof
+            lp = ((inner.get("launch_prompt") if isinstance(inner, dict) else None)
+                  or prof.get("launch_prompt") or "")
+            rd = ((inner.get("role_description") if isinstance(inner, dict) else None)
+                  or prof.get("role_description")
+                  or prof.get("role")
+                  or AGENT_ROLE
+                  or "(unspecified)")
+            _LAUNCH_PROMPT = lp
+            _ROLE_DESCRIPTION = rd
+            log.info(
+                f"agent profile loaded (bg): role='{_ROLE_DESCRIPTION[:60]}' "
+                f"launch_prompt_len={len(_LAUNCH_PROMPT)}"
+            )
+    except Exception as _e:
+        log.warning(f"could not fetch agent profile (bg): {_e}")
 
 
 # ── Leader/commander detection (single source of truth) ───────
@@ -1438,18 +1545,14 @@ def _build_instructions() -> str:
         f"\nUSER-PROVIDED ROLE PROMPT (from the dashboard):\n---\n{_LAUNCH_PROMPT}\n---\n"
         if _LAUNCH_PROMPT else ""
     )
-    # Pull the canonical loop directive from the DB so product can tune it
-    # without a client release. Falls back to the baked-in version below if
-    # the RPC isn't available (older DB) or the call fails.
+    # MIG-PLAN-A 2026-05-18 (boot bug 00d73223 second RC): module-import-time
+    # be.sb_rpc calls block MCP InitializeResult on commander-class agents with
+    # heavy memory payloads, even after mig 312 closed the SDK↔DDL CHECK retry
+    # storm. Defer ALL network I/O out of _build_instructions(). The baked-in
+    # static LOOP directive below is sufficient for boot; if product later
+    # wants live tuning, fetch in BG and inject via memory_hints envelope on
+    # first tool call. NO be.sb_rpc here.
     _db_loop = ""
-    try:
-        _r = be.sb_rpc("mc_get_loop_directive", {})
-        if isinstance(_r, list) and _r:
-            _r = _r[0]
-        if isinstance(_r, str) and _r.strip():
-            _db_loop = _r.strip() + "\n\n"
-    except Exception:
-        pass
 
     base = f"""You are agent "{AGENT_NAME}" in meshwork "{PROJECT_NAME}".{role_block}{launch_block}
 
@@ -1462,6 +1565,8 @@ SESSION START (run NOW, don't wait for input). If tool schemas are deferred:
 Then: set_status(online,ready) → check() → tasks() → auto_wake() → status() → wait(). Don't ask user "what to work on" — the mesh tells you.
 
 COMMUNICATE BY CALLING TOOLS, not by thinking aloud. Cross-mesh: send(to="agent@meshwork"). Reference docs (memory/scratchpad/account ops) → recall agent_protocol_quick_ref when needed.
+
+DECISIONS: when you face a non-trivial pick (architectural choice, risky migration, scope decision), call meshcode_decide(decision, alternatives, evidence_refs) BEFORE acting — returns a trace_id. Call meshcode_outcome(trace_id, outcome, outcome_eval) when the result becomes observable. Use meshcode_explain(memory_key=…) or (decision_substring=…) to surface prior traces + open contradictions. Memory hints with open_contradictions take a -0.2 ranking penalty — treat as a flag, not a veto.
 """
     # Inject commander protocol if this agent is a leader
     is_leader = _is_leader_agent()
@@ -1485,67 +1590,153 @@ COMMANDER PROTOCOL (you are the team lead):
     return base
 
 
+# MIG-PLAN-A 2026-05-18 (boot bug 00d73223 part 2): timer-bracketed
+# _INSTRUCTIONS construction. If module-import-time work exceeds the budget,
+# the regression sentinel (CI) trips so we don't silently regress past the
+# Claude Code MCP-handshake window again. Caught the zylo-commander 17:28
+# repro after mig 312 had already closed the SDK↔DDL retry storm.
+_INSTRUCTIONS_BUILD_NS = _time.monotonic_ns()
 _INSTRUCTIONS = _build_instructions()
+_INSTRUCTIONS_BUILD_NS = _time.monotonic_ns() - _INSTRUCTIONS_BUILD_NS
+log.info(
+    f"_INSTRUCTIONS built in {_INSTRUCTIONS_BUILD_NS/1_000_000:.1f}ms "
+    f"(budget <500ms — MCP handshake window)"
+)
+if _INSTRUCTIONS_BUILD_NS > 500_000_000:
+    log.warning(
+        f"_INSTRUCTIONS build exceeded 500ms budget ({_INSTRUCTIONS_BUILD_NS/1_000_000:.1f}ms) "
+        f"— commander-class agents may fail MCP handshake on slower networks. "
+        f"Investigate any be.sb_rpc / network I/O added to _build_instructions()."
+    )
 
-# Pre-load persistent memories into instructions (tiered, ~10x cheaper than legacy
-# load-all). Strategy:
-#   - critical: full content always preloaded (cap 10 keys per agent)
-#   - reference: key list only (fetch values on demand via meshcode_recall)
-#   - episodic: NEVER preloaded — search via meshcode_recall_search instead
-# Falls back to legacy load-all if migration 080 isn't applied yet (overload missing).
-try:
-    _api_key = _get_api_key()
-    _crit = be.sb_rpc("mc_memory_list", {
-        "p_api_key": _api_key,
-        "p_agent_name": AGENT_NAME,
-        "p_tier": "critical",
-        "p_project_name": PROJECT_NAME,
-    })
-    _ref = be.sb_rpc("mc_memory_list", {
-        "p_api_key": _api_key,
-        "p_agent_name": AGENT_NAME,
-        "p_tier": "reference",
-        "p_project_name": PROJECT_NAME,
-    })
+# ============================================================
+# Install-guard (task dbae99ed 2026-05-18) — detect mid-session
+# pip --force-reinstall over the running env and execv-restart cleanly
+# instead of crashing on lockfile collision. Class:
+# feedback_pip_install_into_live_mcp_env_self_kill weight 9.
+# Paired with stop_hook _mcp_disconnected_without_reconnect (P0 mig
+# 68a3545e) so the brief MCP-socket-drop during execv doesn't trap the
+# Claude Code agent.
+# ============================================================
+from pathlib import Path as _Path  # local-scope; rest of module doesn't need it
+_PKG_DIR = _Path(__file__).resolve().parent.parent  # .../site-packages/meshcode/
 
-    _crit_ok = isinstance(_crit, dict) and _crit.get("ok")
-    _ref_ok = isinstance(_ref, dict) and _ref.get("ok")
-
-    if _crit_ok or _ref_ok:
-        _sections = []
-        if _crit_ok and _crit.get("memories"):
-            _crit_lines = [f"  {m['key']}: {json.dumps(m['value'], default=str)}"
-                           for m in _crit["memories"]]
-            _sections.append("CRITICAL MEMORIES (always loaded):\n" + "\n".join(_crit_lines))
-        if _ref_ok and _ref.get("memories"):
-            _ref_keys = [m["key"] for m in _ref["memories"]]
-            _sections.append(
-                "REFERENCE MEMORIES (key list — fetch on demand via meshcode_recall(key)):\n  "
-                + ", ".join(_ref_keys)
+def _snapshot_pkg_mtimes():
+    out = {}
+    try:
+        for p in _PKG_DIR.rglob("*.py"):
+            try:
+                out[str(p)] = p.stat().st_mtime
+            except OSError:
+                continue
+    except Exception:
+        pass
+    return out
+
+_PKG_PY_MTIMES = _snapshot_pkg_mtimes()
+log.info(f"install-guard: snapshotted {len(_PKG_PY_MTIMES)} *.py mtimes under {_PKG_DIR}")
+
+
+def _install_guard_check() -> None:
+    """Heartbeat-tick scan: if any *.py under the meshcode pkg path has
+    a fresher mtime than recorded at boot, the env was reinstalled while
+    the process is alive (class feedback_pip_install_into_live_mcp_env_self_kill).
+    The running image holds stale bytecode; lockfile collision and
+    orphan-watchdog will eventually kill us anyway. Pre-empt: release the
+    lease and execv-restart so the new wheel is picked up cleanly.
+
+    The MCP socket to Claude Code WILL drop during the exec window.
+    Stop_hook _mcp_disconnected_without_reconnect (mig 68a3545e) catches
+    it; user runs `meshcode go <agent>` to pick up the new wheel.
+
+    Soft-fail throughout: any exception here is logged and swallowed so
+    the heartbeat thread isn't taken down by a flaky filesystem call.
+    """
+    if not _PKG_PY_MTIMES:
+        return
+    try:
+        for path, old_mtime in list(_PKG_PY_MTIMES.items()):
+            try:
+                new_mtime = os.path.getmtime(path)
+            except OSError:
+                continue
+            # 0.5s slack — covers fs-timestamp resolution and tar extract
+            # re-emit jitter without false-positive on intentional touch.
+            if new_mtime <= old_mtime + 0.5:
+                continue
+            log.warning(
+                f"install-guard: self-modification detected on {path} "
+                f"(mtime {old_mtime:.0f} → {new_mtime:.0f}). The running "
+                f"image holds stale bytecode; triggering clean execv-restart "
+                f"so the new wheel is picked up. MCP socket will drop briefly "
+                f"— stop_hook handles the agent release (mig 68a3545e). User "
+                f"runs `meshcode go <agent>` to relaunch under the new image. "
+                f"Class: feedback_pip_install_into_live_mcp_env_self_kill."
             )
-        _sections.append(
-            "EPISODIC MEMORIES: not preloaded. Search via "
-            "meshcode_recall_search(query) when you need past incident context."
-        )
-        _INSTRUCTIONS += "\n" + "\n\n".join(_sections) + "\n"
-        log.info(
-            f"pre-loaded tiered memories: critical={len(_crit.get('memories', [])) if _crit_ok else 0}, "
-            f"reference={len(_ref.get('memories', [])) if _ref_ok else 0}"
-        )
-    else:
-        # Legacy fallback: migration 080 not applied → load all (old behavior)
-        _legacy = be.sb_rpc("mc_memory_list", {
-            "p_api_key": _api_key,
+            try:
+                _release_lease_synchronous(timeout_s=1.5)
+            except Exception:
+                pass
+            _heartbeat_stop.set()
+            # execv replaces the current process; daemon threads die with
+            # it; new process inherits stdio. We pass the original argv so
+            # the entry-point command line is preserved verbatim.
+            try:
+                os.execv(sys.executable, [sys.executable] + sys.argv)
+            except Exception as _exec_err:
+                log.error(
+                    f"install-guard execv failed ({_exec_err}); "
+                    f"falling back to os._exit(0). Lifespan finally + "
+                    f"stop_hook still recover."
+                )
+                os._exit(0)
+            return  # unreachable but explicit
+    except Exception as e:
+        log.debug(f"install-guard scan failed (soft): {e}")
+
+# MIG-PLAN-A 2026-05-18: memory pre-load deferred to BG daemon thread.
+# Was synchronous mc_memory_list (critical+reference tiers + legacy fallback)
+# that appended to module-global _INSTRUCTIONS at import time. On commander-
+# class agents with heavy memory accumulation, this exceeded Claude Code's
+# MCP InitializeResult window → "MCP tools not in deferred list" until
+# manual /mcp reconnect. Two prior partial fixes: fe57b7a5 mode-a (persona +
+# boot_context BG) and mig 312 (SDK↔DDL needs_launch CHECK). Plan A is the
+# remaining piece. Memory content is still surfaced — just via the
+# memory_hints envelope on the first meshcode_check / meshcode_boot tool
+# call instead of via MCP InitializeResult.instructions. Tradeoff: handshake
+# guaranteed <1s vs first-tool result ~1s heavier. Net wins handshake budget.
+_PRELOADED_CRITICAL: Optional[List[Dict[str, Any]]] = None
+_PRELOADED_REFERENCE_KEYS: Optional[List[str]] = None
+
+def _preload_memories_bg() -> None:
+    """Run by daemon thread spawned at lifespan start. Populates module-
+    global _PRELOADED_* used by memory_hints envelope. Soft-fail; consumers
+    fall through to live RPC paths if globals stay None."""
+    global _PRELOADED_CRITICAL, _PRELOADED_REFERENCE_KEYS
+    try:
+        api_key = _get_api_key()
+        crit = be.sb_rpc("mc_memory_list", {
+            "p_api_key": api_key,
             "p_agent_name": AGENT_NAME,
+            "p_tier": "critical",
             "p_project_name": PROJECT_NAME,
         })
-        if isinstance(_legacy, dict) and _legacy.get("ok") and _legacy.get("memories"):
-            _mem_lines = [f"  {m['key']}: {json.dumps(m['value'], default=str)}"
-                          for m in _legacy["memories"]]
-            _INSTRUCTIONS += "\nPRE-LOADED MEMORIES (legacy):\n" + "\n".join(_mem_lines) + "\n"
-            log.info(f"pre-loaded {len(_mem_lines)} memories (legacy fallback)")
-except Exception as _e:
-    log.debug(f"memory pre-load skipped: {_e}")
+        ref = be.sb_rpc("mc_memory_list", {
+            "p_api_key": api_key,
+            "p_agent_name": AGENT_NAME,
+            "p_tier": "reference",
+            "p_project_name": PROJECT_NAME,
+        })
+        if isinstance(crit, dict) and crit.get("ok"):
+            _PRELOADED_CRITICAL = crit.get("memories") or []
+        if isinstance(ref, dict) and ref.get("ok"):
+            _PRELOADED_REFERENCE_KEYS = [m["key"] for m in (ref.get("memories") or []) if "key" in m]
+        log.info(
+            f"memory pre-load (bg): critical={len(_PRELOADED_CRITICAL or [])} "
+            f"reference_keys={len(_PRELOADED_REFERENCE_KEYS or [])}"
+        )
+    except Exception as e:
+        log.debug(f"memory pre-load (bg) skipped: {e}")
 
 
 # ============================================================
@@ -1846,6 +2037,11 @@ def _heartbeat_loop_inner():
             except Exception:
                 pass
 
+            # Install-guard tick (task dbae99ed). Cheap mtime scan over
+            # ~100-200 *.py files; if any changed since boot, we execv-
+            # restart cleanly before lockfile collision kills us.
+            _install_guard_check()
+
             _hb_resp = be.sb_rpc("mc_heartbeat", {"p_project_id": _PROJECT_ID, "p_agent_name": AGENT_NAME, "p_version": _SDK_VERSION})
 
             # Tombstone gate (mig 211): user disconnected this agent.
@@ -2104,6 +2300,13 @@ async def lifespan(_app):
 
     _threading.Thread(target=_load_persona_bg, daemon=True, name="meshcode-load-persona").start()
     _threading.Thread(target=_load_boot_context_bg, daemon=True, name="meshcode-load-boot-context").start()
+    # MIG-PLAN-A 2026-05-18: memory pre-load deferred from module-import-time
+    # to here. Soft-fail consumers read from _PRELOADED_CRITICAL / _PRELOADED_REFERENCE_KEYS.
+    _threading.Thread(target=_preload_memories_bg, daemon=True, name="meshcode-preload-memories").start()
+    # MIG-PLAN-A 2026-05-18 part 2: agent profile fetch deferred. Was the
+    # last be.sb_rpc that ran at module-import time. Closes the import-time
+    # zero-network goal for the CI regression sentinel.
+    _threading.Thread(target=_load_agent_profile_bg, daemon=True, name="meshcode-load-profile").start()
 
     # Heartbeat in daemon thread — independent of asyncio event loop.
     _heartbeat_stop.clear()
@@ -3341,6 +3544,7 @@ async def _meshcode_wait_inner(actual_timeout: int, include_acks: bool) -> Dict[
 
 @mcp.tool()
 @with_working_status
+@with_decision_gate
 def meshcode_done(reason: str) -> Dict[str, Any]:
     """Broadcast DONE to all agents — exits everyone's wait loop.
 
@@ -4603,6 +4807,7 @@ def meshcode_edit_agent(name: str, role: Optional[str] = None, launch_prompt: Op
 
 @mcp.tool()
 @with_working_status
+@with_decision_gate
 def meshcode_edit_memory(agent_name: str, key: str, value: Any) -> Dict[str, Any]:
     """Edit another agent's memory (for commanders coordinating the team).
 
@@ -4831,6 +5036,7 @@ def meshcode_recall_keys() -> Dict[str, Any]:
 
 @mcp.tool()
 @with_working_status
+@with_decision_gate
 def meshcode_forget(key: str) -> Dict[str, Any]:
     """Delete a stored memory.
 
@@ -4868,6 +5074,99 @@ def meshcode_recall_search(query: str) -> Dict[str, Any]:
     })
 
 
+# ----------------- EPISTEMIC V1 (decide / outcome / explain) -----------------
+# mig 305-308 SQL substrate; mig 313 memory_hints contradictions + ranking;
+# mig 314 public.* wrappers. Task b4befbfd.
+
+@mcp.tool()
+@with_working_status
+def meshcode_decide(
+    decision: str,
+    alternatives: Optional[List[str]] = None,
+    evidence_refs: Optional[List[Dict[str, Any]]] = None,
+    tier: str = "episodic",
+) -> Dict[str, Any]:
+    """Log a non-trivial decision to mc_traces (architectural choice, risky migration,
+    scope decision). Returns {trace_id}. Pair with meshcode_outcome later when the
+    result becomes observable so the team can learn from outcomes.
+
+    Args:
+        decision: What you decided (one sentence).
+        alternatives: Other options you considered (list of strings).
+        evidence_refs: Pointers to evidence (list of {type, id|key} dicts).
+            type values: 'memory','msg','task','file','rpc'.
+        tier: 'episodic' (default) | 'reference' | 'critical'.
+    """
+    if not decision or not decision.strip():
+        return {"ok": False, "error": "decision required"}
+    return be.sb_rpc("mc_decide", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_decision": decision.strip(),
+        "p_alternatives": json.dumps(alternatives or []),
+        "p_evidence_refs": json.dumps(evidence_refs or []),
+        "p_tier": tier,
+    })
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_outcome(
+    trace_id: str,
+    outcome: str,
+    outcome_eval: str,
+) -> Dict[str, Any]:
+    """Record the observable outcome of a prior decision (logged via meshcode_decide).
+    Call this when results become visible — even partial results help future-you and
+    the team learn what worked.
+
+    Args:
+        trace_id: UUID returned by meshcode_decide.
+        outcome: Free-form description of what happened.
+        outcome_eval: 'success' | 'failure' | 'partial' | 'unknown'.
+    """
+    if outcome_eval not in ("success", "failure", "partial", "unknown"):
+        return {"ok": False, "error": "outcome_eval must be success|failure|partial|unknown"}
+    return be.sb_rpc("mc_outcome", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_trace_id": trace_id,
+        "p_outcome": outcome,
+        "p_outcome_eval": outcome_eval,
+    })
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_explain(
+    memory_key: Optional[str] = None,
+    decision_substring: Optional[str] = None,
+    trace_limit: int = 20,
+) -> Dict[str, Any]:
+    """Surface recent traces + open contradictions tied to a memory key or decision
+    substring. Use when you want to understand why a memory ranks the way it does,
+    or recall the chain of reasoning around a past choice. Exactly one of
+    (memory_key, decision_substring) is required.
+
+    Args:
+        memory_key: Match traces whose evidence_refs reference this key.
+        decision_substring: ILIKE match against the decision text.
+        trace_limit: Cap on returned traces (1..200, default 20).
+    """
+    if not memory_key and not decision_substring:
+        return {"ok": False, "error": "one of (memory_key, decision_substring) required"}
+    return be.sb_rpc("mc_explain", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_memory_key": memory_key,
+        "p_decision_substring": decision_substring,
+        "p_trace_limit": trace_limit,
+    })
+
+
 # ----------------- BUG REPORTING -----------------
 
 @mcp.tool()

{meshcode-2.11.5 → meshcode-2.11.7}/meshcode.egg-info/PKG-INFO

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

{meshcode-2.11.5 → meshcode-2.11.7}/meshcode.egg-info/SOURCES.txt

@@ -190,10 +190,13 @@ meshcode/meshcode_mcp/test_server_wrapper.py
 meshcode/scripts/check_secrets.py
 meshcode/scripts/race_rate_harness.py
 tests/test_auto_update_hardening.py
+tests/test_boot_bug_regression.py
 tests/test_core.py
 tests/test_cross_agent_messaging.py
+tests/test_epistemic_v1_stop_conditions.py
 tests/test_esc_deaf_state.py
 tests/test_exceptions.py
+tests/test_install_guard.py
 tests/test_lease_sigterm_release.py
 tests/test_mark_read_batch.py
 tests/test_migration_integrity.py

{meshcode-2.11.5 → meshcode-2.11.7}/pyproject.toml

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