mcp-switchboard-client 0.3.0.dev5__tar.gz → 0.4.0.dev6__tar.gz

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/.gitignore

@@ -1,3 +1,4 @@
+node_modules/
 __pycache__/
 *.pyc
 *.egg-info/

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-switchboard-client
-Version: 0.3.0.dev5
+Version: 0.4.0.dev6
 Summary: Tunnels local stdio MCP servers to an mcp-switchboard hub over one outbound WebSocket
 Project-URL: Homepage, https://github.com/AkosPapp/mcp-switchboard
 Project-URL: Repository, https://github.com/AkosPapp/mcp-switchboard

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-switchboard-client"
-version = "0.3.0.dev5"
+version = "0.4.0.dev6"
 description = "Tunnels local stdio MCP servers to an mcp-switchboard hub over one outbound WebSocket"
 readme = "README.md"
 requires-python = ">=3.10"

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/src/mcp_switchboard_client/__init__.py

@@ -6,4 +6,4 @@ outbound WebSocket, tagged with the server name. Every MCP concern lives in the
 hub. See docs/PROTOCOL.md.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/src/mcp_switchboard_client/cli.py

@@ -56,6 +56,7 @@ class Settings:
     environment: Optional[Dict[str, Any]] = None  # detected at load_settings
     instruction_root: Optional[str] = None  # cwd by default; None disables shipping
     env_brief: bool = True  # host brief in hello + context_update
+    skills: bool = True  # SKILL.md skills in hello + skills_update
 
     def tunnel_settings(self) -> TunnelSettings:
         return TunnelSettings(
@@ -67,6 +68,7 @@ class Settings:
             environment=self.environment,
             instruction_root=self.instruction_root,
             env_brief=self.env_brief,
+            skills=self.skills,
         )
 
 
@@ -170,6 +172,14 @@ def build_parser() -> argparse.ArgumentParser:
             f"tool presence) to the hub (or set {envconf.PREFIX}ENV_BRIEF=false)"
         ),
     )
+    parser.add_argument(
+        "--no-skills",
+        action="store_true",
+        help=(
+            "Do not scan SKILL.md skills (~/.claude/skills, .opencode/skills, ...) on this "
+            f"host or report them to the hub (or set {envconf.PREFIX}SKILLS=false)"
+        ),
+    )
     return parser
 
 
@@ -257,6 +267,7 @@ def load_settings(args: argparse.Namespace) -> Settings:
             else str(Path.cwd())
         ),
         env_brief=not args.no_env_brief and envconf.get_bool("ENV_BRIEF", True),
+        skills=not args.no_skills and envconf.get_bool("SKILLS", True),
     )
 
 

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/src/mcp_switchboard_client/environment.py

@@ -313,6 +313,121 @@ def collect_instructions(cwd: Path) -> List[Dict[str, str]]:
     return out
 
 
+# ---------- Skills (hello skills / skills_update) -----------------------------
+#
+# SKILL.md directories on this host, scanned the same way instruction files are
+# (hello + a refresh frame; docs/PROTOCOL.md). opencode/Claude discovery
+# locations; the hub stores them read-only under skills/hosts/<label>/ and can
+# promote copies into its managed library. Budgets mirror the instruction ones.
+
+SKILL_MAX_SKILLS = 200
+SKILL_MAX_FILE_CHARS = 64 * 1024  # per SKILL.md
+SKILL_MAX_TOTAL_CHARS = 256 * 1024  # per hello/skills_update
+
+_SKILL_DIR_SETS = (".claude", ".opencode", ".agents")
+_CONFIG_SKILL_DIRS = (
+    (".claude", "skills"),
+    (".config/opencode", "skills"),
+    (".agents", "skills"),
+)
+SKILL_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def _frontmatter_value(text: str, key: str) -> Optional[str]:
+    """First top-level ``key: value`` scalar from a ``---`` frontmatter block."""
+    if not text.startswith("---"):
+        return None
+    lines = text.splitlines()
+    for line in lines[1:]:
+        if line.strip() in ("---", "..."):
+            break
+        if not line or line[0] in " \t#-":
+            continue
+        m = re.match(rf"^{key}:\s*(.*)$", line)
+        if not m:
+            continue
+        value = m.group(1).strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        return value
+    return None
+
+
+def _scanned_skill_dir(d: Path, base: Path, source: str) -> List[Dict[str, Any]]:
+    """Valid skills from one ``.../skills/`` directory, sorted by name."""
+    found: List[Dict[str, Any]] = []
+    try:
+        if not d.is_dir():
+            return found
+        entries = sorted(p for p in d.iterdir() if p.is_dir())
+    except OSError:
+        return found
+    for skill_dir in entries:
+        name = skill_dir.name
+        if not SKILL_NAME_RE.match(name) or len(name) > 64:
+            continue
+        try:
+            text = (skill_dir / "SKILL.md").read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        fm_name = _frontmatter_value(text, "name") or name
+        if fm_name != name:  # name must match the directory (opencode rule)
+            continue
+        description = _frontmatter_value(text, "description") or ""
+        if len(text) > SKILL_MAX_FILE_CHARS:
+            text = text[:SKILL_MAX_FILE_CHARS]
+        try:
+            path = skill_dir.relative_to(base).as_posix() + "/SKILL.md"
+        except ValueError:
+            path = str(skill_dir)
+        found.append({"name": name, "path": path, "source": source,
+                      "description": description[:1024], "content": text})
+    return found
+
+
+def scan_skills(cwd: Optional[Path] = None, home: Optional[Path] = None) -> List[Dict[str, Any]]:
+    """Every SKILL.md skill visible to an agent on this host, within budgets.
+
+    Global locations come first (``~/.claude/skills`` etc., ``source`` names the
+    location), then project locations at ``cwd`` and every ancestor up to the
+    git root; an earlier source wins a name clash, and only name/description/
+    content travel. Never raises.
+    """
+    out: List[Dict[str, str]] = []
+    try:
+        cwd = Path(cwd) if cwd is not None else Path(os.getcwd())
+        home = Path(home) if home is not None else Path.home()
+        seen: set = set()
+        used = 0
+
+        def add(found: List[Dict[str, Any]]) -> None:
+            nonlocal used
+            for item in found:
+                if len(out) >= SKILL_MAX_SKILLS or item["name"] in seen:
+                    continue
+                cost = len(item["content"]) + len(item["description"]) + len(item["name"])
+                if used + cost > SKILL_MAX_TOTAL_CHARS:
+                    continue
+                used += cost
+                seen.add(item["name"])
+                out.append(item)
+
+        for first, second in _CONFIG_SKILL_DIRS:
+            add(_scanned_skill_dir(home / first / second, home, f"global:{first}/{second}"))
+        git_root = find_git_root(cwd)
+        roots: List[Path] = []
+        for directory in _parents(cwd):
+            roots.append(directory)
+            if git_root is not None and directory == git_root:
+                break
+        for directory in roots:
+            for d in _SKILL_DIR_SETS:
+                add(_scanned_skill_dir(directory / d / "skills", directory, f"project:{d}/skills"))
+    except Exception:  # noqa: BLE001 - scanning must never break the tunnel
+        LOGGER.debug("skill scan failed", exc_info=True)
+    return out
+
+
 # ---------- Environment brief (hello environment_brief / context_update) -----
 #
 # A short, cheaply-computed description of the client host so the agent knows
@@ -428,7 +543,7 @@ def collect_environment_brief(
         lines.append(
             "file tools can write: the root, scratch "
             f"{scratch} (unless overridden), and temp {tempfile.gettempdir()}; "
-            "run_command/run_python are UNCONFINED and can write anything this user can"
+            "bash and the process_* tools are UNCONFINED and can write anything this user can"
         )
         lines.append(
             "harness output cap: "

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/src/mcp_switchboard_client/protocol.py

@@ -21,6 +21,7 @@ SERVER_STATE = "server_state"
 RESTART = "restart"
 ERROR = "error"
 CONTEXT_UPDATE = "context_update"
+SKILLS_UPDATE = "skills_update"
 
 STATE_STARTING = "starting"
 STATE_RUNNING = "running"
@@ -53,6 +54,7 @@ def hello(
     environment: Optional[Dict[str, Any]] = None,
     instructions: Optional[List[Dict[str, str]]] = None,
     environment_brief: Optional[str] = None,
+    skills: Optional[List[Dict[str, str]]] = None,
 ) -> Dict[str, Any]:
     client: Dict[str, Any] = {"name": client_name, "version": version, "instance": instance, "label": label}
     if environment is not None:
@@ -61,6 +63,8 @@ def hello(
         client["instructions"] = instructions
     if environment_brief is not None:
         client["environment_brief"] = environment_brief
+    if skills is not None:
+        client["skills"] = skills
     return {
         "type": HELLO,
         "protocol": PROTOCOL_VERSION,
@@ -88,6 +92,16 @@ def context_update(
     return frame
 
 
+def skills_update(skills: List[Dict[str, str]]) -> Dict[str, Any]:
+    """Replace the hub's copy of the skills scanned on this host.
+
+    The list is complete (an empty list means the host has none), mirrors the
+    context_update wholesale-replacement contract, is additive (protocol
+    version stays 1), and hubs that do not know the frame ignore it.
+    """
+    return {"type": SKILLS_UPDATE, "skills": skills}
+
+
 def hello_ack(connection_id: str, hub_name: str, hub_version: str) -> Dict[str, Any]:
     return {
         "type": HELLO_ACK,

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/src/mcp_switchboard_client/tunnel.py

@@ -22,6 +22,7 @@ import logging
 import os
 import random
 import ssl
+import time
 import uuid
 from contextlib import suppress
 from dataclasses import dataclass
@@ -49,6 +50,12 @@ MAX_BACKOFF_DELAY = 60.0
 PING_INTERVAL = 20
 PING_TIMEOUT = 10
 
+# A session must hold this long after hello_ack before a drop re-bases the
+# reconnect backoff. Without it, two clients sharing a label evict each other
+# at the reconnect rate forever (every eviction looks like a fresh successful
+# session). See the hub evict path: it sends the explanatory error frame.
+STABLE_CONNECTION = 15.0
+
 _WS_SCHEMES = {"ws": "ws", "wss": "wss", "http": "ws", "https": "wss"}
 
 
@@ -169,6 +176,9 @@ class TunnelSettings:
     # The host brief (identity, git, tools, scratch) ships with every hello
     # too and refreshes via context_update; --no-env-brief turns it off.
     env_brief: bool = True
+    # SKILL.md skills scanned on this host ship with every hello and refresh
+    # via skills_update; --no-skills turns it off.
+    skills: bool = True
 
 
 class HubConnection:
@@ -201,10 +211,18 @@ class HubConnection:
         self._ws: Any = None
         self._acked = False
         self._session_ok = False
+        # hello_ack's monotonic clock, for the stable-session backoff rule, and
+        # the hub's "a newer client took this label" flag (see STABLE_CONNECTION
+        # and _handle_error); both refreshed per connection in _connect_and_serve.
+        self._ack_at = 0.0
+        self._replaced = False
+        # last sleep the run loop asked for, exposed for tests and triage
+        self.last_reconnect_delay: Optional[float] = None
         # Last instruction set and host brief sent on the live connection
         # (None = never), for the context_update freshness loop.
         self._instructions_last: Optional[List[Dict[str, str]]] = None
         self._brief_last: Optional[str] = None
+        self._skills_last: Optional[List[Dict[str, str]]] = None
         self._stopping = False
         self._stop_event: Optional[asyncio.Event] = None
         # Set when run() ended because the tunnel gave up (fatal rejection or
@@ -252,8 +270,16 @@ class HubConnection:
                 if self._stopping:
                     break
 
-                if self._session_ok:
-                    # A session that got as far as hello_ack starts backoff over.
+                stable = (
+                    self._session_ok
+                    and not self._replaced
+                    and time.monotonic() - self._ack_at >= STABLE_CONNECTION
+                )
+                if stable:
+                    # ONLY a session that reached hello_ack AND held it for
+                    # STABLE_CONNECTION starts the backoff over: a connection
+                    # the hub dropped (or replaced) within that window is churn
+                    # to damp, not success to forget.
                     attempt = 0
 
                 attempt += 1
@@ -266,11 +292,16 @@ class HubConnection:
                     )
                     break
 
+                # The exponent is bounded before the power: `2 ** attempt` as
+                # an int never overflows on its own, but multiplying it into a
+                # float does — an infinite-retry client that never connects
+                # would crash outright once attempt passed ~1024.
                 delay = min(
-                    self.settings.reconnect_delay * (2 ** (attempt - 1)),
+                    self.settings.reconnect_delay * (2 ** min(attempt - 1, 40)),
                     MAX_BACKOFF_DELAY,
                 )
                 delay *= 1 + random.uniform(-BACKOFF_JITTER, BACKOFF_JITTER)
+                self.last_reconnect_delay = delay
                 LOGGER.info("reconnecting in %.1fs (attempt %d)", delay, attempt)
                 if await self._sleep_or_stop(delay):
                     break
@@ -309,6 +340,8 @@ class HubConnection:
     async def _connect_and_serve(self) -> None:
         self._acked = False
         self._session_ok = False
+        self._replaced = False
+        self._ack_at = 0.0
         kwargs = {
             _header_kwarg(): {"Authorization": f"Bearer {self.settings.token}"},
             "ping_interval": PING_INTERVAL,
@@ -323,6 +356,7 @@ class HubConnection:
             closer = asyncio.create_task(self._close_when_stopped(ws))
             self._instructions_last = self._collect_instructions()
             self._brief_last = self._collect_brief()
+            self._skills_last = self._collect_skills()
             try:
                 await self._send(
                     protocol.hello(
@@ -334,6 +368,7 @@ class HubConnection:
                         self.settings.environment,
                         self._instructions_last,
                         environment_brief=self._brief_last,
+                        skills=self._skills_last,
                     )
                 )
                 refresh = asyncio.create_task(self._context_refresh_loop())
@@ -427,6 +462,7 @@ class HubConnection:
         )
         self._acked = True
         self._session_ok = True
+        self._ack_at = time.monotonic()
         # The hub opens a fresh MCP session per connection, and a server that
         # already completed `initialize` would reject a second one, so every
         # (re)connect restarts every local server. See docs/PROTOCOL.md.
@@ -469,6 +505,14 @@ class HubConnection:
     def _handle_error(self, data: Dict[str, Any]) -> None:
         message = data.get("message") or "unspecified error"
         server = data.get("server")
+        if self._acked and _is_label_in_use(message):
+            # The hub replaced this connection with a newer one carrying the
+            # same label (a second live client). Keep reconnecting, but this
+            # session must not re-base the backoff, or two such clients evict
+            # each other at the reconnect rate forever.
+            self._replaced = True
+            LOGGER.warning("superseded by a newer connection for label %r: %s", self.settings.label, message)
+            return
         if not self._acked:
             # Before hello_ack an error means the hub refused this client -
             # unsupported protocol version, illegal server name. Retrying with
@@ -549,15 +593,27 @@ class HubConnection:
         # None (not "") so an old hub omits the field when collection is off.
         return environment.collect_environment_brief(root, instruction_paths=paths) or None
 
+    def _collect_skills(self) -> Optional[List[Dict[str, str]]]:
+        """Scanned SKILL.md skills for hello, or None when the feature is off.
+
+        None (not []) also covers a host with no skills on an old hub: the
+        field simply disappears; a hub that knows the feature reads the empty
+        list back as skills_update when they change.
+        """
+        if not self.settings.skills:
+            return None
+        root = Path(self.settings.instruction_root or os.getcwd())
+        return environment.scan_skills(root) or None
+
     async def _context_refresh_loop(self) -> None:
-        """Re-read instruction files and the host brief; push a context_update on change.
+        """Re-read instruction files, the host brief and the skills; push updates on change.
 
         The hub re-injects the fresh text from the next turn on, so editing
         AGENTS.md mid-session actually reaches the agent (P1-A acceptance) and
         a changing git state keeps the brief honest (P2-B). Each refresh resets
         the hub's staleness clock for whatever it carries.
         """
-        if not (self.settings.instruction_root or self.settings.env_brief):
+        if not (self.settings.instruction_root or self.settings.env_brief or self.settings.skills):
             return
         interval = max(self.settings.instructions_interval, 0.2)
         while True:
@@ -566,9 +622,11 @@ class HubConnection:
             await asyncio.sleep(interval)
             current = self._collect_instructions()
             brief = self._collect_brief(current)
+            skills = self._collect_skills()
             changed_files = current != self._instructions_last
             changed_brief = brief != self._brief_last
-            if not (changed_files or changed_brief):
+            changed_skills = skills != self._skills_last
+            if not (changed_files or changed_brief or changed_skills):
                 continue
             kwargs: Dict[str, Any] = {}
             if changed_files and self.settings.instruction_root:
@@ -576,14 +634,22 @@ class HubConnection:
             if changed_brief and self.settings.env_brief:
                 kwargs["environment_brief"] = brief or ""
             self._instructions_last, self._brief_last = current, brief
-            try:
-                await self._send(protocol.context_update(**kwargs))
-                LOGGER.info(
-                    "sent context_update: %s",
-                    ", ".join(sorted(kwargs)) or "no carried fields",
-                )
-            except Exception as e:  # noqa: BLE001 - the read loop owns the connection
-                LOGGER.debug("context_update send failed (connection dropping?): %s", e)
+            if kwargs:
+                try:
+                    await self._send(protocol.context_update(**kwargs))
+                    LOGGER.info(
+                        "sent context_update: %s",
+                        ", ".join(sorted(kwargs)) or "no carried fields",
+                    )
+                except Exception as e:  # noqa: BLE001 - the read loop owns the connection
+                    LOGGER.debug("context_update send failed (connection dropping?): %s", e)
+            if changed_skills and self.settings.skills:
+                self._skills_last = skills
+                try:
+                    await self._send(protocol.skills_update(skills or []))
+                    LOGGER.info("sent skills_update: %d skills", len(skills or []))
+                except Exception as e:  # noqa: BLE001 - same reason
+                    LOGGER.debug("skills_update send failed (connection dropping?): %s", e)
 
     async def _send(self, frame: Dict[str, Any]) -> None:
         ws = self._ws

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/tests/test_instructions.py

@@ -142,6 +142,7 @@ def make_connection(tmp_path, ws, **overrides):
         max_retries=1,
         instruction_root=str(root) if root is not None else None,
         instructions_interval=overrides.pop("instructions_interval", 0.2),
+        skills=overrides.pop("skills", False),  # the shared factory keeps scanning off unless asked
         **overrides,
     )
     return HubConnection(SPECS, settings, version="0", connect=FakeConnect([ws]), server_factory=FakeServer)
@@ -177,7 +178,7 @@ async def test_hello_omits_instructions_when_disabled(tmp_path):
 async def test_refresh_loop_pushes_context_update_on_change(tmp_path):
     (tmp_path / "AGENTS.md").write_text("before\n")
     ws = FakeWebSocket([])
-    connection = make_connection(tmp_path, ws, instructions_interval=0.2, env_brief=False)
+    connection = make_connection(tmp_path, ws, instructions_interval=0.2, env_brief=False, skills=False)
     sent = []
 
     async def fake_send(frame):
@@ -213,7 +214,7 @@ async def test_refresh_loop_pushes_context_update_on_change(tmp_path):
 
 async def test_refresh_loop_stays_quiet_when_disabled(tmp_path):
     ws = FakeWebSocket([])
-    connection = make_connection(tmp_path, ws, instruction_root=None, env_brief=False)
+    connection = make_connection(tmp_path, ws, instruction_root=None, env_brief=False, skills=False)
 
     async def fake_send(frame):
         raise AssertionError("must not send")

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/tests/test_protocol_conformance.py

@@ -53,6 +53,7 @@ def test_frame_type_constants_match_the_manifest() -> None:
         protocol.RESTART,
         protocol.ERROR,
         protocol.CONTEXT_UPDATE,
+        protocol.SKILLS_UPDATE,
     }
     assert declared == set(MANIFEST["frames"])
 
@@ -60,12 +61,16 @@ def test_frame_type_constants_match_the_manifest() -> None:
 # One builder call per frame, with arguments chosen so that every optional field is
 # populated - a builder that silently dropped a field would otherwise pass.
 INSTRUCTION_FILES = [{"path": "AGENTS.md", "content": "# rules\n"}]
+SKILLS = [
+    {"name": "pdf", "path": ".claude/skills/pdf/SKILL.md", "source": "project:.claude/skills",
+     "description": "PDF work", "content": "---\nname: pdf\ndescription: PDF work\n---\nbody\n"},
+]
 
 BUILDERS = {
     "hello": lambda: protocol.hello(
         "c", "0.0.0", "i", "lab", [{"name": "git"}],
         {"kinds": ["direnv"], "workspace": "/w"}, INSTRUCTION_FILES,
-        environment_brief="user: uid=1 me\n",
+        environment_brief="user: uid=1 me\n", skills=SKILLS,
     ),
     "hello_ack": lambda: protocol.hello_ack("cid", "hub", "0.0.0"),
     "mcp": lambda: protocol.mcp("git", {"jsonrpc": "2.0"}),
@@ -73,6 +78,7 @@ BUILDERS = {
     "restart": lambda: protocol.restart("git"),
     "error": lambda: protocol.error("bad", "git"),
     "context_update": lambda: protocol.context_update(INSTRUCTION_FILES),
+    "skills_update": lambda: protocol.skills_update(SKILLS),
 }
 
 
@@ -96,16 +102,18 @@ def test_every_builder_is_covered() -> None:
 
 def test_hello_client_optional_fields_are_declared_and_emitted() -> None:
     declared = MANIFEST["frames"]["hello"]["clientOptional"]
-    assert set(declared) >= {"environment", "instructions", "environment_brief"}
+    assert set(declared) >= {"environment", "instructions", "environment_brief", "skills"}
     client = protocol.hello(
-        "c", "0.0.0", "i", "lab", [], {"kinds": []}, INSTRUCTION_FILES, environment_brief="host: x\n"
+        "c", "0.0.0", "i", "lab", [], {"kinds": []}, INSTRUCTION_FILES,
+        environment_brief="host: x\n", skills=SKILLS,
     )["client"]
     assert set(client) <= {"name", "version", "instance", "label"} | set(declared)
     assert client["environment"] == {"kinds": []}
     assert client["instructions"] == INSTRUCTION_FILES
     assert client["environment_brief"] == "host: x\n"
+    assert client["skills"] == SKILLS
     omitted = protocol.hello("c", "0.0.0", "i", "lab", [])["client"]
-    assert not {"environment", "instructions", "environment_brief"} & set(omitted)
+    assert not {"environment", "instructions", "environment_brief", "skills"} & set(omitted)
 
 
 def test_context_update_fields_are_independently_optional() -> None:

mcp_switchboard_client-0.4.0.dev6/tests/test_skill_scan.py

@@ -0,0 +1,171 @@
+"""Client-side skill scanning: discovery locations, frontmatter rules,
+budgets, hello shipping and skills_update refresh — mirroring the instruction
+file pipeline (docs/PROTOCOL.md)."""
+
+import asyncio
+import json
+
+import pytest
+
+from mcp_switchboard_client import environment, protocol
+from mcp_switchboard_client.config import ServerSpec
+from mcp_switchboard_client.tunnel import HubConnection, TunnelSettings
+
+from test_tunnel import FakeConnect, FakeServer, FakeWebSocket
+
+pytestmark = pytest.mark.asyncio
+
+SKILL_MD = "---\nname: {name}\ndescription: does {name} things\n---\nDo {name} well.\n"
+
+
+def write_skill(root, name, text=None):
+    d = root / name
+    d.mkdir(parents=True)
+    (d / "SKILL.md").write_text(text if text is not None else SKILL_MD.format(name=name))
+    return d
+
+
+# ---------- collection (pure) ------------------------------------------
+
+
+def test_global_locations_are_scanned(tmp_path):
+    home = tmp_path / "home"
+    write_skill(home / ".claude" / "skills", "pdf")
+    write_skill(home / ".config" / "opencode" / "skills", "docx")
+    write_skill(home / ".agents" / "skills", "pptx")
+    found = {s["name"]: s for s in environment.scan_skills(tmp_path / "proj", home)}
+    assert set(found) == {"pdf", "docx", "pptx"}
+    assert found["pdf"]["source"] == "global:.claude/skills"
+    assert found["pdf"]["description"] == "does pdf things"
+    assert "Do pdf well." in found["pdf"]["content"]
+
+
+def test_project_locations_up_to_git_root(tmp_path):
+    home = tmp_path / "home"
+    home.mkdir()
+    repo = tmp_path / "repo"
+    (repo / ".git").mkdir(parents=True)
+    deep = repo / "sub" / "deeper"
+    deep.mkdir(parents=True)
+    write_skill(repo / ".claude" / "skills", "repo-skill")
+    write_skill(deep / ".opencode" / "skills", "deep-skill")
+    outside = tmp_path / "other"
+    write_skill(outside / ".claude" / "skills", "outside")
+    found = {s["name"] for s in environment.scan_skills(deep, home)}
+    assert found == {"repo-skill", "deep-skill"}
+
+
+def test_invalid_names_and_missing_frontmatter_are_skipped(tmp_path):
+    home = tmp_path / "home"
+    skills = home / ".claude" / "skills"
+    write_skill(skills, "Upper-Case")
+    write_skill(skills, "bad--name")
+    write_skill(skills, "empty-dir")
+    (skills / "empty-dir" / "SKILL.md").unlink()
+    (skills / "loose.txt").write_text("x")
+    # name in frontmatter must match the directory
+    write_skill(skills, "mismatch", "---\nname: other\ndescription: d\n---\nbody\n")
+    write_skill(skills, "no-frontmatter", "just text, no frontmatter\n")
+    found = {s["name"] for s in environment.scan_skills(tmp_path, home)}
+    # no-frontmatter files default the name to the (valid, matching) directory
+    assert found == {"no-frontmatter"}
+
+
+def test_frontmatter_values_are_unquoted(tmp_path):
+    home = tmp_path / "home"
+    write_skill(
+        home / ".claude" / "skills", "quoted",
+        '---\nname: quoted\ndescription: "a quoted: description"\nmetadata:\n  audience: maintainers\n---\nbody\nmore body\n',
+    )
+    (skill,) = environment.scan_skills(tmp_path, home)
+    assert skill["description"] == "a quoted: description"
+    assert skill["content"].endswith("more body\n")
+
+
+def test_global_wins_a_name_clash(tmp_path):
+    home = tmp_path / "home"
+    write_skill(home / ".claude" / "skills", "dup")
+    write_skill(tmp_path / "proj" / ".claude" / "skills", "dup")
+    found = environment.scan_skills(tmp_path / "proj", home)
+    assert [s["source"] for s in found if s["name"] == "dup"] == ["global:.claude/skills"]
+
+
+def test_oversized_files_are_cut_to_their_budget(tmp_path):
+    home = tmp_path / "home"
+    skills = home / ".claude" / "skills"
+    write_skill(skills, "big", SKILL_MD.format(name="big") + "x" * (environment.SKILL_MAX_FILE_CHARS + 10))
+    (found,) = environment.scan_skills(tmp_path, home)
+    assert len(found["content"]) <= environment.SKILL_MAX_FILE_CHARS
+
+
+def test_scan_never_raises(tmp_path):
+    assert environment.scan_skills(tmp_path / "does-not-exist", tmp_path / "no-home") == []
+
+
+# ---------- hello + skills_update wiring --------------------------------
+
+
+def _skill(name="pdf"):
+    return {"name": name, "path": f"{name}/SKILL.md", "source": "global:.claude/skills",
+            "description": "d", "content": "body"}
+
+
+def _make(tmp_path, sessions, **overrides):
+    settings = TunnelSettings(
+        hub_url="https://hub.example.com", token="s3cret", label="legion5",
+        reconnect_delay=0.0, max_retries=1,
+        instruction_root=None, env_brief=False,
+        **overrides,
+    )
+    specs = [ServerSpec(name="noop", argv=["true"])]
+    connect = FakeConnect(sessions)
+    return HubConnection(specs, settings, version="0.4.0", connect=connect, server_factory=FakeServer)
+
+
+async def test_hello_carries_scanned_skills(tmp_path, monkeypatch):
+    monkeypatch.setattr(environment, "scan_skills", lambda cwd=None, home=None: [_skill()])
+    ws = FakeWebSocket([protocol.hello_ack("c1", "hub", "1.0")])
+    connection = _make(tmp_path, [ws], skills=True)
+    await connection.run()
+    hello = ws.frames("hello")[0]
+    assert hello["client"]["skills"][0]["name"] == "pdf"
+
+
+async def test_skills_off_omits_the_field(tmp_path, monkeypatch):
+    monkeypatch.setattr(environment, "scan_skills", lambda cwd=None, home=None: [])
+    ws = FakeWebSocket([protocol.hello_ack("c1", "hub", "1.0")])
+    connection = _make(tmp_path, [ws], skills=False)
+    await connection.run()
+    hello = ws.frames("hello")[0]
+    assert "skills" not in hello["client"]
+
+
+async def test_refresh_loop_sends_skills_update_on_change(tmp_path, monkeypatch):
+    scans = [[_skill("a")], [_skill("a"), _skill("b")]]
+    monkeypatch.setattr(
+        environment, "scan_skills",
+        lambda cwd=None, home=None: scans.pop(0) if scans else [_skill("a"), _skill("b")],
+    )
+    ws = FakeWebSocket([])
+    connection = _make(tmp_path, [ws], skills=True, instructions_interval=0.05)
+    sent = []
+
+    async def fake_send(frame):
+        sent.append(frame)
+
+    connection._send = fake_send
+    connection._skills_last = connection._collect_skills()
+
+    task = asyncio.create_task(connection._context_refresh_loop())
+    try:
+        await asyncio.sleep(0.1)
+        assert sent == [], "an unchanged set must not churn the wire"
+        for _ in range(100):
+            await asyncio.sleep(0.02)
+            if sent:
+                break
+        assert len(sent) == 1
+        assert sent[0]["type"] == protocol.SKILLS_UPDATE
+        assert [s["name"] for s in sent[0]["skills"]] == ["a", "b"]
+    finally:
+        task.cancel()

{mcp_switchboard_client-0.3.0.dev5 → mcp_switchboard_client-0.4.0.dev6}/tests/test_tunnel.py

@@ -420,3 +420,89 @@ def test_tls_context_keeps_the_system_store_too(monkeypatch, tmp_path):
     monkeypatch.setenv("SSL_CERT_FILE", str(pem))
     assert len(tunnel._tls_context().get_ca_certs()) >= 1
     assert baseline >= 1
+
+
+# -- label-replacement damping (eviction-tennis guard) --------------------
+
+
+def _replacement_ws():
+    """A session that acks, learns it was replaced, and drops — like a second
+    live client on the same label sees, over and over."""
+    return FakeWebSocket([
+        protocol.hello_ack("c1", "hub", "0.1"),
+        protocol.error('label "legion5" is already connected from a newer connection; this one is replaced', ""),
+    ])
+
+
+async def test_replaced_after_ack_is_flagged_not_fatal():
+    ws = FakeWebSocket([
+        protocol.hello_ack("c1", "hub", "0.1"),
+        protocol.error('label "legion5" is already connected from a newer connection', ""),
+    ])
+    connection, _ = make_connection([ws], max_retries=1)
+    await connection.run()
+    # The point: post-ack "already connected" never raises (the run loop ran
+    # to its normal give-up), and it flags the session as churn instead.
+    assert connection._replaced is True
+
+
+async def test_backoff_keeps_growing_across_fast_replacements():
+    """Three ack-then-replaced sessions in a row must grow the delay (attempt
+    1,2,3), not restart at the base every time like plain success would."""
+    delays = []
+    connection, _ = make_connection([], max_retries=4)
+    connection.settings.reconnect_delay = 0.5
+
+    async def fake_sleep(delay):
+        delays.append(delay)
+        return False
+
+    connection._sleep_or_stop = fake_sleep
+    await connection.run()
+    assert connection.failure is not None and "giving up" in connection.failure
+    assert len(delays) == 3
+    assert delays[1] > delays[0] and delays[2] > delays[1], f"backoff did not grow: {delays}"
+
+
+class _HeldThenClose(FakeWebSocket):
+    """Acks, holds the session open, then the stream ends (a clean drop)."""
+
+    def __init__(self, hold):
+        super().__init__([protocol.hello_ack("c1", "hub", "0.1")])
+        self._hold = hold
+
+    async def __anext__(self):
+        if self.inbound:
+            return self.inbound.pop(0)
+        await asyncio.sleep(self._hold)
+        raise StopAsyncIteration
+
+
+def connection_stop(connection):
+    connection.request_stop()
+
+
+async def test_stable_session_re_bases_the_backoff(monkeypatch):
+    monkeypatch.setattr(tunnel_mod, "STABLE_CONNECTION", 0.05)
+    delays = []
+    sessions = [
+        _replacement_ws(),            # churn 1 -> attempt 1
+        _HeldThenClose(0.3),          # holds past the stability window
+        _replacement_ws(),            # churn 2 -> attempt was reset -> smallest delay
+        _replacement_ws(),            # exhausts the retry budget
+    ]
+    connection, _ = make_connection(sessions, max_retries=3)
+    connection.settings.reconnect_delay = 0.5
+
+    async def fake_sleep(delay):
+        delays.append(delay)
+        return len(delays) >= 3
+
+    connection._sleep_or_stop = fake_sleep
+    await connection.run()
+    assert len(delays) == 3
+    # Without the stable-session rule these would be ~1x, 2x, 4x of the base.
+    # With it: the churn before the stable session is 1x, the drop after the
+    # stable session is re-based to ~1x again, and plain churn grows from there.
+    assert delays[1] < delays[0] * 1.5, f"no re-base after the stable session: {delays}"
+    assert delays[2] > delays[1], f"growth must simply start over: {delays}"