arbora 0.1.8.dev11__tar.gz → 0.1.8.dev12__tar.gz

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbora
-Version: 0.1.8.dev11
+Version: 0.1.8.dev12
 Summary: The deployable MCP, REST, control-plane, fleet, WebUI, and operations composition for the Knuckles agent platform.
 Author-email: Repository Maintainers <maintainers@knuckles.team>
 License-Expression: MIT

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/_version.py

@@ -3,4 +3,4 @@
 Updated only by `bump-my-version` (see `.bumpversion.toml`) — never hand-edited.
 """
 
-__version__ = "0.1.8.dev11"
+__version__ = "0.1.8.dev12"

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/api/ops/fleet.py

@@ -105,6 +105,10 @@ class FleetPinsListParams(_Params):
     limit: int = Field(default=50, ge=1, le=100)
 
 
+class FleetCatalogRefreshParams(_Params):
+    servers: tuple[str, ...] = Field(min_length=1, max_length=32)
+
+
 class FleetCallParams(_Params):
     server: str = Field(min_length=1, max_length=128)
     tool: str = Field(min_length=1, max_length=128)
@@ -191,6 +195,8 @@ async def handle_fleet_operation(
         result = await gateway.pin(caller, **params)
     elif op.id == "fleet.tools.unpin":
         result = await gateway.unpin(caller, **params)
+    elif op.id == "fleet.catalog.refresh":
+        result = await gateway.catalog_refresh(caller, **params)
     elif op.id == "fleet.pins.list":
         result = await gateway.pins_list(caller, **params)
     elif op.id == "fleet.prompts.list":
@@ -359,6 +365,18 @@ def operations() -> tuple[OpSpec, ...]:
                 ),
             )
         ),
+        OpSpec(
+            id="fleet.catalog.refresh",
+            verb=Verb.MANAGE,
+            summary="Re-read connector tool catalogs now, without an arbora restart",
+            examples=("refresh the tool catalog of craft-suite-api",),
+            params=FleetCatalogRefreshParams,
+            result=FleetResult,
+            binding=Composite(handler="arbora.api.ops.fleet.handle_fleet_operation"),
+            scopes=frozenset({"fleet:control"}),
+            effect=Effect.WRITE,
+            audit=AuditClass.EVENT,
+        ),
         OpSpec(
             id="fleet.pins.list",
             verb=Verb.ASK,
@@ -462,6 +480,7 @@ specs = operations
 __all__ = [
     "FleetCallParams",
     "FleetCatalogParams",
+    "FleetCatalogRefreshParams",
     "FleetLoadParams",
     "FleetPackStatusParams",
     "FleetPinParams",

arbora-0.1.8.dev12/arbora/fleet/catalog_composition.py

@@ -0,0 +1,277 @@
+"""Bind the existing EG reader and multiplexer cache to fleet operations."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from typing import Any, Protocol, cast
+
+from arbora.fleet.catalog_items import CatalogItem, FleetCatalog
+from arbora.fleet.catalog_sources import CombinedFleetSource, SdkRead
+from arbora.fleet.multiplexer_ops import (
+    CoverageEndpoints,
+    CoverageRegistry,
+    Invoke,
+    Loadable,
+    Mount,
+    MultiplexerOps,
+    NativeName,
+    Notify,
+    ReadItem,
+    SessionKeyFor,
+    UnadmittedServers,
+)
+from arbora.fleet.pin_store import PinStore
+from arbora.fleet.session_loads import SessionLoads
+
+logger = logging.getLogger(__name__)
+
+
+class VerifiedReader(Protocol):
+    async def read(self) -> Any: ...
+
+
+class CachedProbe(Protocol):
+    _probe_cache: Mapping[str, Mapping[str, Any]]
+
+    def status_snapshot(self) -> Mapping[str, Any]: ...
+
+
+async def _cached_protocol(mux: CachedProbe) -> Mapping[str, Mapping[str, Any]]:
+    """Use completed probes only; discovery never starts a fleet sweep here."""
+    return dict(mux._probe_cache)
+
+
+#: A server whose probe failed or is never cached (an OAuth-gated child) is
+#: not re-probed before this many seconds. A cached probe that is later
+#: invalidated is re-probed on the next request. An explicit refresh of one
+#: server runs at most once per window too.
+PRIME_RETRY_S = 60.0
+#: One server's priming probe may take at most this long.
+PRIME_TIMEOUT_S = 20.0
+
+
+def _good(info: Mapping[str, Any] | None) -> bool:
+    return isinstance(info, Mapping) and info.get("error") is None
+
+
+def _summary(info: Mapping[str, Any] | None) -> dict[str, Any]:
+    """The caller-visible outcome of one refresh: a count, never the tools."""
+    if not isinstance(info, Mapping):
+        return {"tools": 0, "error": "refresh failed"}
+    return {
+        "tools": len(info.get("tools") or ()),
+        "error": info.get("error"),
+        "probed_at": info.get("probed_at"),
+    }
+
+
+class ProbePrimer:
+    """Keep the probed half of the fleet catalog current.
+
+    The verified EG catalog carries no input schema or tool annotations; the
+    live probe does. Calling the primer probes only the servers a request
+    names, so the served path never sweeps the fleet. A probe past the
+    multiplexer's TTL is served while one background re-probe runs
+    (ARBORA-FLEET-R070), and :meth:`refresh` re-reads a server at once, for a
+    ``fleet.call`` of a tool the catalog does not know yet (ARBORA-FLEET-R071)
+    and for the explicit refresh operation. A failed re-probe is logged and
+    leaves the last good probe in place.
+    """
+
+    def __init__(
+        self,
+        mux: Any,
+        *,
+        retry_s: float = PRIME_RETRY_S,
+        timeout_s: float = PRIME_TIMEOUT_S,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._mux = mux
+        self._probe = getattr(mux, "probe_server", None)
+        self._retry_s = retry_s
+        self._timeout_s = timeout_s
+        self._clock = clock
+        self._attempted: dict[str, float] = {}
+        self._refreshed: dict[str, float] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._background: dict[str, asyncio.Task[Any]] = {}
+
+    def _throttled(self, stamps: Mapping[str, float], server: str) -> bool:
+        last = stamps.get(server)
+        return last is not None and self._clock() - last < self._retry_s
+
+    def _fresh(self, server: str) -> bool:
+        if not _good(self._mux._probe_cache.get(server)):
+            return False
+        hit = getattr(self._mux, "_probe_cache_hit", None)
+        return hit is None or hit(server) is not None
+
+    def _keep_last_good(self, server: str, previous: Any) -> None:
+        if _good(previous) and not _good(self._mux._probe_cache.get(server)):
+            logger.warning("fleet re-probe of %s failed; keeping its catalog", server)
+            self._mux._probe_cache[server] = previous
+
+    async def _probe_once(self, server: str, *, force: bool) -> Any:
+        """Probe one server; a good cached result clears its retry window."""
+        probe = cast(Callable[..., Awaitable[Any]], self._probe)
+        previous = self._mux._probe_cache.get(server)
+        self._attempted[server] = self._clock()
+        run = probe(server, force=True) if force else probe(server)
+        try:
+            info = await asyncio.wait_for(run, timeout=self._timeout_s)
+        except Exception as exc:  # noqa: BLE001 - priming is best-effort
+            logger.warning(
+                "fleet probe of %s for catalog schema failed: %s",
+                server,
+                type(exc).__name__,
+            )
+            info = None
+        self._keep_last_good(server, previous)
+        if _good(self._mux._probe_cache.get(server)):
+            # The window throttles failed and never-cached probes only.
+            # A cached probe that a later schema refresh drops must be
+            # re-primed on the next request, or its tools lose their
+            # annotations and a read-only tool resolves as a write.
+            self._attempted.pop(server, None)
+        return info
+
+    def _lock(self, server: str) -> asyncio.Lock:
+        return self._locks.setdefault(server, asyncio.Lock())
+
+    async def _reprobe_stale(self, server: str) -> None:
+        async with self._lock(server):
+            if not self._fresh(server):
+                await self._probe_once(server, force=False)
+
+    def _refresh_in_background(self, server: str) -> None:
+        task = self._background.get(server)
+        if (task is not None and not task.done()) or self._throttled(
+            self._attempted, server
+        ):
+            return
+        self._background[server] = asyncio.ensure_future(self._reprobe_stale(server))
+
+    async def __call__(self, servers: Iterable[str]) -> None:
+        if self._probe is None:
+            return
+        for server in _named(servers):
+            if self._fresh(server):
+                continue
+            if _good(self._mux._probe_cache.get(server)):
+                self._refresh_in_background(server)
+                continue
+            async with self._lock(server):
+                if _good(self._mux._probe_cache.get(server)) or self._throttled(
+                    self._attempted, server
+                ):
+                    continue
+                await self._probe_once(server, force=False)
+
+    async def refresh(self, servers: Iterable[str]) -> dict[str, dict[str, Any]]:
+        """Re-probe each named server now, at most once per retry window."""
+        outcome: dict[str, dict[str, Any]] = {}
+        if self._probe is None:
+            return outcome
+        for server in _named(servers):
+            async with self._lock(server):
+                info: Any = self._mux._probe_cache.get(server)
+                if not self._throttled(self._refreshed, server):
+                    self._refreshed[server] = self._clock()
+                    info = await self._probe_once(server, force=True)
+                    info = self._mux._probe_cache.get(server, info)
+            outcome[server] = _summary(info)
+        return outcome
+
+
+def _named(servers: Iterable[str]) -> list[str]:
+    return [server for server in servers if isinstance(server, str) and server]
+
+
+def probe_primer(
+    mux: Any,
+    *,
+    retry_s: float = PRIME_RETRY_S,
+    timeout_s: float = PRIME_TIMEOUT_S,
+    clock: Callable[[], float] = time.monotonic,
+) -> ProbePrimer:
+    """The primer for one multiplexer; see :class:`ProbePrimer`."""
+    return ProbePrimer(mux, retry_s=retry_s, timeout_s=timeout_s, clock=clock)
+
+
+def compose_multiplexer_ops(
+    *,
+    reader: VerifiedReader,
+    mux: CachedProbe,
+    sdk_entries: SdkRead,
+    visible: Callable[[CatalogItem, Any], Awaitable[bool]],
+    loadable: Loadable,
+    callable_item: Loadable,
+    mount: Mount,
+    notify: Notify,
+    invoke: Invoke,
+    session_key_for: SessionKeyFor,
+    native_name: NativeName | None = None,
+    read_item: ReadItem | None = None,
+    cap: int = 64,
+    pinned_cap: int | None = None,
+    idle_ttl_seconds: int = 3600,
+    pin_store: PinStore | None = None,
+    coverage_registry: CoverageRegistry | None = None,
+    coverage_endpoints: CoverageEndpoints | None = None,
+    unadmitted_servers: UnadmittedServers | None = None,
+) -> MultiplexerOps:
+    """Build one operation service without claiming the MCP cutover is wired.
+
+    ``reader`` is the process's already-bound ``DeferredFleetCatalogReader``.
+    ``mux`` is the same process singleton used by the MCP server. The
+    discovery/load-authorization policy owns ``visible``/``loadable``, and
+    the native MCP tool registration and list-changed notification path owns
+    the ``mount``/``notify`` hooks; supplying neither cannot silently widen
+    authority. ``pinned_cap`` defaults to the ``FLEET_PINNED_CAP`` setting;
+    ``pin_store`` is the durable per-principal pin store (without one the pin
+    operations refuse ``UNAVAILABLE``).
+    """
+
+    async def live() -> Mapping[str, Mapping[str, Any]]:
+        return await _cached_protocol(mux)
+
+    prime = probe_primer(mux)
+    source = CombinedFleetSource(verified=reader.read, live=live, sdk=sdk_entries)
+    catalog = FleetCatalog((source,), visible)
+
+    def health() -> Mapping[str, Any]:
+        return mux.status_snapshot().get("children", {})
+
+    if pinned_cap is None:
+        from arbora.core.settings import runtime_config
+
+        pinned_cap = runtime_config.fleet_pinned_cap
+    if unadmitted_servers is None:
+
+        def unadmitted_servers():
+            return list(mux.status_snapshot().get("unadmitted_servers", ()))
+
+    return MultiplexerOps(
+        catalog=catalog,
+        sessions=SessionLoads(
+            cap=cap, pinned_cap=pinned_cap, idle_ttl_seconds=idle_ttl_seconds
+        ),
+        loadable=loadable,
+        callable_item=callable_item,
+        mount=mount,
+        notify=notify,
+        invoke=invoke,
+        health=health,
+        session_key_for=session_key_for,
+        native_name=native_name,
+        read_item=read_item,
+        prime=prime,
+        refresh=prime.refresh,
+        pin_store=pin_store,
+        coverage_registry=coverage_registry,
+        coverage_endpoints=coverage_endpoints,
+        unadmitted_servers=unadmitted_servers,
+    )

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/fleet/gateway_ops.py

@@ -551,6 +551,12 @@ class FleetGateway:
             caller, items=params.get("items", ())
         )
 
+    async def catalog_refresh(self, caller: Any, **params: Any) -> Any:
+        # The op's own scopes (fleet:control) gate the pipeline.
+        return await self._catalog(caller, "fleet:control").refresh_catalog(
+            caller, servers=params.get("servers", ())
+        )
+
     async def pins_list(self, caller: Any, **params: Any) -> Any:
         # The op's own scopes (fleet:control, mcp:admin) gate the pipeline;
         # the tenant-wide read needs no session of the caller's.

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/fleet/multiplexer.py

@@ -138,10 +138,12 @@ _MAX_DELEGATED_VALUE_BYTES = 4 * 1024 * 1024
 _MAX_CHILD_SSE_EVENT_BYTES = 2 * _MAX_DELEGATED_VALUE_BYTES
 _MAX_DELEGATED_NODES = 16_384
 _MAX_DELEGATED_DEPTH = 32
-_MAX_DISCOVERED_TOOLS = 2_048
-# A child catalog is metadata, not a single tool invocation.  It legitimately
-# contains hundreds of independently bounded JSON Schemas, so it gets its own
-# aggregate structural allowance while retaining the same byte/depth limits.
+#: Resource and prompt listings keep a fixed per-child count bound. A tool
+#: catalog has no count bound at all (ARBORA-FLEET-R069): a connector that
+#: serves one tool per upstream operation is admitted whole.
+_MAX_DISCOVERED_DESCRIPTORS = 2_048
+#: One child tool descriptor's structural allowance. Each descriptor is
+#: bounded on its own; a large catalog is never truncated (ARBORA-FLEET-R069).
 _MAX_CATALOG_NODES = 131_072
 # Skills-over-MCP (CONCEPT:MERISTEM-ECO.mcp.skills-over-mcp-provider): a probed
 # server's Resources may include ``skill://{name}/SKILL.md`` entries. Bounded
@@ -857,31 +859,80 @@ def _bounded_tool_entry(tool: _typing.Any) -> dict[str, _typing.Any]:
     return item
 
 
+class FleetCatalogPageError(RuntimeError):
+    """One page of a child's ``tools/list`` could not be read.
+
+    Typed (ARBORA-FLEET-R068): the listing is refused whole, never served
+    partial, so a connector can never silently lose tools. The probe records
+    it as the server's error and the primer retries; the last good catalog
+    keeps serving meanwhile.
+    """
+
+
 def _bounded_tool_catalog(raw_tools: _typing.Any) -> list[dict[str, _typing.Any]]:
     """Project one child catalog into a bounded, JSON-compatible shape.
 
     The MCP SDK decodes remote responses before returning them to us.  This
     boundary prevents a child from turning that decoded value into an
-    unbounded in-memory/KG catalog: tool count, aggregate bytes, nesting,
-    collection size, names, descriptions, schemas, and annotations are all
-    validated before any caller can cache or register them.
+    unbounded in-memory/KG catalog: names, descriptions, schemas, and
+    annotations are validated per descriptor before any caller can cache or
+    register them. The tool count has no bound (ARBORA-FLEET-R069).
     """
 
-    if (
-        not isinstance(raw_tools, list | tuple)
-        or len(raw_tools) > _MAX_DISCOVERED_TOOLS
-    ):
+    if not isinstance(raw_tools, list | tuple):
         raise RuntimeError("MCP child tool catalog exceeded its boundary")
     tools: list[dict[str, _typing.Any]] = [
         _bounded_tool_entry(tool) for tool in raw_tools
     ]
     try:
-        _assert_bounded_json_value(tools, max_nodes=_MAX_CATALOG_NODES)
+        for entry in tools:
+            _assert_bounded_json_value(entry, max_nodes=_MAX_CATALOG_NODES)
     except _fastmcp_exceptions.ToolError:
         raise RuntimeError("MCP child tool catalog exceeded its boundary") from None
     return tools
 
 
+def _next_cursor(result: _typing.Any) -> str | None:
+    """A ``tools/list`` page's continuation cursor, or ``None`` on the last."""
+    cursor = getattr(result, "next_cursor", None)
+    return cursor if isinstance(cursor, str) and cursor else None
+
+
+async def _list_page(session: _typing.Any, cursor: str | None) -> _typing.Any:
+    try:
+        if cursor is None:
+            return await session.list_tools()
+        return await session.list_tools(
+            params=mcp_types.PaginatedRequestParams(cursor=cursor)
+        )
+    except Exception as exc:
+        raise FleetCatalogPageError(
+            f"MCP child tools/list page failed ({type(exc).__name__})"
+        ) from exc
+
+
+async def _list_all_tools(session: _typing.Any) -> list[_typing.Any]:
+    """Every tool a child serves: ``tools/list`` followed to its last page.
+
+    ARBORA-FLEET-R068: a child that paginates is read cursor by cursor until
+    it returns no ``nextCursor``. A failed page or a repeated cursor refuses
+    the listing whole with :class:`FleetCatalogPageError`; a partial catalog
+    is never returned.
+    """
+    result = await _list_page(session, None)
+    tools = list(result.tools)
+    seen: set[str] = set()
+    cursor = _next_cursor(result)
+    while cursor is not None:
+        if cursor in seen:
+            raise FleetCatalogPageError("MCP child tools/list cursor repeated")
+        seen.add(cursor)
+        result = await _list_page(session, cursor)
+        tools.extend(result.tools)
+        cursor = _next_cursor(result)
+    return tools
+
+
 def _tool_catalog_digest(tools: list[MCPTool]) -> str:
     """Return a stable digest of the client-visible portion of one child catalog.
 
@@ -913,7 +964,7 @@ def _assert_bounded_resource_list(raw_resources: _typing.Any) -> None:
 
     if not isinstance(raw_resources, list | tuple):
         raise RuntimeError("MCP child resource catalog is invalid")
-    if len(raw_resources) > _MAX_DISCOVERED_TOOLS:
+    if len(raw_resources) > _MAX_DISCOVERED_DESCRIPTORS:
         raise RuntimeError("MCP child resource catalog exceeded its boundary")
 
 
@@ -921,7 +972,10 @@ def _bounded_descriptor_catalog(
     values: _typing.Any, *, key: str, family: str
 ) -> list[dict[str, _typing.Any]]:
     """Project one native MCP descriptor family through the shared boundary."""
-    if not isinstance(values, list | tuple) or len(values) > _MAX_DISCOVERED_TOOLS:
+    if (
+        not isinstance(values, list | tuple)
+        or len(values) > _MAX_DISCOVERED_DESCRIPTORS
+    ):
         raise RuntimeError(f"MCP child {family} catalog exceeded its boundary")
     projected: list[dict[str, _typing.Any]] = []
     for value in values:
@@ -3165,8 +3219,7 @@ class MCPMultiplexer:
         ``record_state=False``: an ephemeral per-principal session must never
         write into the process-wide admitted-tool map.
         """
-        tools_result = await session.list_tools()
-        tools = list(tools_result.tools)
+        tools = await _list_all_tools(session)
         admitted = self._oauth_admitted_tools(
             server_name, original_name, runtime_policy, tools
         )
@@ -4134,7 +4187,8 @@ class MCPMultiplexer:
             if session is None:
                 return
             try:
-                tools = list((await session.list_tools()).tools)
+                tools = await _list_all_tools(session)
+                _bounded_tool_catalog(tools)
             except Exception as exc:
                 logger.warning(
                     "list_changed refresh of %s failed: %s",
@@ -4142,6 +4196,10 @@ class MCPMultiplexer:
                     redact_for_log(exc),
                 )
                 return
+            # ARBORA-FLEET-R070: the new list replaces the served one now,
+            # without a restart; the next catalog read re-probes the child.
+            self._probe_cache.pop(server_name, None)
+            await self._publish_live_tools(server_name, tools)
             await self._announce_handshake(server_name, session, tools, "list_changed")
 
         async def handler(message: IncomingMessage) -> None:
@@ -4272,9 +4330,8 @@ class MCPMultiplexer:
             sessions = [
                 await _connect_one(stack, generation_secret) for _ in range(pool_size)
             ]
-            tools_result = await sessions[0].list_tools()
-            _bounded_tool_catalog(tools_result.tools)
-            tools = list(tools_result.tools)
+            tools = await _list_all_tools(sessions[0])
+            _bounded_tool_catalog(tools)
             await self._announce_handshake(server_name, sessions[0], tools)
             if runtime_policy is not None:
                 tools = self._admit_runtime_policy_tools(
@@ -4765,6 +4822,35 @@ class MCPMultiplexer:
         self._retract_removed_from_sessions(stale_names - set(refreshed_by_name))
         return refreshed, True
 
+    async def _publish_live_tools(
+        self, server_name: str, tools: list[_typing.Any]
+    ) -> None:
+        """Serve a mounted child's re-listed tools (ARBORA-FLEET-R070).
+
+        The same policy admission and schema refresh a new child generation
+        gets; a child that is not mounted has nothing to publish.
+        """
+        runtime = self.children.get(server_name)
+        if runtime is None:
+            return
+        cfg = self.load_catalog().get(server_name)
+        if cfg is None:
+            return
+        policy = self._child_runtime_policies.get(server_name)
+        if policy is not None:
+            tools = self._admit_runtime_policy_tools(server_name, policy, tools)
+        await self._refresh_child_tools(
+            server_name, runtime, cfg, self._catalog_epoch, tools
+        )
+
+    async def _relist_live_child(self, server_name: str) -> None:
+        """Re-read a mounted child's whole tool list on its live session."""
+        session = self._live_primary_session(server_name)
+        tools = await _list_all_tools(session)
+        _bounded_tool_catalog(tools)
+        await self._publish_live_tools(server_name, tools)
+        await self._announce_handshake(server_name, session, tools)
+
     async def _refresh_child_tools(
         self,
         server_name: str,
@@ -5495,6 +5581,8 @@ class MCPMultiplexer:
                 return cached
 
         if server_name in self.children:
+            if force:
+                await self._relist_live_child(server_name)
             return await self._live_child_probe(server_name)
 
         cfg = self.load_catalog().get(server_name)
@@ -5536,9 +5624,12 @@ class MCPMultiplexer:
                     session = await self._open_one_session(
                         server_name, runtime_cfg, stack
                     )
-                    result = await session.list_tools()
-                    _bounded_tool_catalog(result.tools)
-                    tools = list(result.tools)
+                    tools = await _list_all_tools(session)
+                    _bounded_tool_catalog(tools)
+                    if force:
+                        # An explicit refresh also re-onboards a changed
+                        # catalog into the engine (ARBORA-FLEET-R070).
+                        await self._announce_handshake(server_name, session, tools)
                     if runtime_policy is not None:
                         tools = self._admit_runtime_policy_tools(
                             server_name,

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/fleet/multiplexer_ops.py

@@ -24,6 +24,10 @@ NativeName = Callable[[CatalogItem], str]
 ReadItem = Callable[[CatalogItem, Mapping[str, Any], Any], Awaitable[Any]]
 #: Fill the live protocol rows (input schema, annotations) of named servers.
 Prime = Callable[[Iterable[str]], Awaitable[None]]
+#: Re-probe named servers now; answers each server's tool count and error.
+Refresh = Callable[[Iterable[str]], Awaitable[Mapping[str, Any]]]
+#: The most servers one explicit catalog refresh names.
+MAX_REFRESH_SERVERS = 32
 #: The coverage registry reader and endpoint lister for ``status``.
 CoverageRegistry = Callable[[], tuple[Any, ...]]
 CoverageEndpoints = Callable[[], tuple[Any, ...]]
@@ -157,6 +161,7 @@ class MultiplexerOps:
         native_name: NativeName | None = None,
         read_item: ReadItem | None = None,
         prime: Prime | None = None,
+        refresh: Refresh | None = None,
         pin_store: PinStore | None = None,
         coverage_registry: CoverageRegistry | None = None,
         coverage_endpoints: CoverageEndpoints | None = None,
@@ -164,6 +169,7 @@ class MultiplexerOps:
     ) -> None:
         self.catalog = catalog
         self._prime = prime or _no_prime
+        self._refresh = refresh
         self.sessions = sessions
         self._loadable = loadable
         self._mount = mount
@@ -190,13 +196,14 @@ class MultiplexerOps:
         # target's live probe does. Without it a read-only tool resolves as
         # a write, and the caller never learns the tool's parameters.
         await self._prime((server,))
-        item = await self.catalog._raw_get(f"fleet:tool:{server}/{tool}")
-        if (
-            item is None
-            or item.kind != "tool"
-            or item.server != server
-            or item.name != tool
-        ):
+        item = await self._tool_item(server, tool)
+        if item is None and self._refresh is not None:
+            # ARBORA-FLEET-R071: authority is the current catalog. A tool the
+            # cached catalog does not hold is re-read from its server once
+            # (throttled per server) before the call is refused.
+            await self._refresh((server,))
+            item = await self._tool_item(server, tool)
+        if item is None:
             raise PermissionError("fleet tool is unavailable")
         if not item.required_scopes.issubset(caller.effective_scopes):
             raise PermissionError("child scopes are required")
@@ -207,6 +214,40 @@ class MultiplexerOps:
             raise PermissionError("fleet call denied by policy")
         return item
 
+    async def _tool_item(self, server: str, tool: str) -> CatalogItem | None:
+        item = await self.catalog._raw_get(f"fleet:tool:{server}/{tool}")
+        if (
+            item is None
+            or item.kind != "tool"
+            or item.server != server
+            or item.name != tool
+        ):
+            return None
+        return item
+
+    async def refresh_catalog(
+        self, caller: Any, *, servers: Iterable[str] = ()
+    ) -> dict[str, Any]:
+        """Re-read the named servers' catalogs now, without a restart.
+
+        ARBORA-FLEET-R070: the explicit refresh. Each server answers its tool
+        count and probe error; a changed catalog is re-onboarded into the
+        engine through the handshake. The op's own scopes gate the caller.
+        """
+        from arbora.api.invoke.pipeline import OperationRefused
+
+        named = tuple(dict.fromkeys(servers))
+        if not 1 <= len(named) <= MAX_REFRESH_SERVERS:
+            raise OperationRefused(
+                "INVALID_ARGUMENT",
+                {"reason": f"name 1..{MAX_REFRESH_SERVERS} servers"},
+            )
+        if self._refresh is None:
+            raise OperationRefused(
+                "UNAVAILABLE", {"reason": "the catalog refresh is unavailable"}
+            )
+        return {"servers": dict(await self._refresh(named))}
+
     async def admitted_surface_item(
         self, caller: Any, family: str, server: str, ident: str
     ) -> CatalogItem:

{arbora-0.1.8.dev11 → arbora-0.1.8.dev12}/arbora/mcp_server/fleet_composition.py

@@ -95,6 +95,10 @@ class LateFleetGateway:
         with _caller_session(caller):
             return await self._bound().unpin(caller, **params)
 
+    async def catalog_refresh(self, caller: Any, **params: Any) -> Any:
+        with _caller_session(caller):
+            return await self._bound().catalog_refresh(caller, **params)
+
     async def pins_list(self, caller: Any, **params: Any) -> Any:
         with _caller_session(caller):
             return await self._bound().pins_list(caller, **params)