agent-core-busproxy 0.8.1__py3-none-any.whl

agent_core_busproxy/__init__.py

@@ -0,0 +1 @@
+"""agent-core-busproxy — stdio MCP proxy to the daemon bus tool surface."""

agent_core_busproxy/__main__.py

@@ -0,0 +1,37 @@
+"""Typer CLI for agent-core-busproxy.
+
+Runs a FastMCP proxy over stdio, backed by the daemon's per-agent HTTP
+endpoint. Spawned by Claude Code as a stdio MCP server; its lifetime is
+the Claude Code session, decoupled from the daemon's lifetime.
+"""
+
+from __future__ import annotations
+
+import anyio
+import typer
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command()
+def main(
+    agent: str = typer.Option(..., "--agent", help="Agent name on the bus."),
+    daemon_url: str = typer.Option(
+        "http://127.0.0.1:8789",
+        "--daemon-url",
+        help="agent-core daemon URL (default: http://127.0.0.1:8789).",
+    ),
+) -> None:
+    """Run the agent-core stdio bus proxy."""
+    from agent_core_busproxy.proxy import build_busproxy
+
+    proxy = build_busproxy(agent=agent, daemon_url=daemon_url)
+
+    async def _run() -> None:
+        await proxy.run_async(transport="stdio")
+
+    anyio.run(_run)
+
+
+if __name__ == "__main__":
+    app()

agent_core_busproxy/proxy.py

@@ -0,0 +1,117 @@
+"""Assemble the stdio bus proxy.
+
+The proxy forwards the daemon's per-agent MCP tool surface. Each tool
+call mints a FRESH backend session (ProxyClient.new()), so a restarted
+daemon is never presented a stale mcp-session-id — issue #91 is removed
+by construction, not by recovery logic.
+
+Cache hardening (spec Amendment 2026-05-16): FastMCP's ProxyProvider
+caches the backend tool list and swallows a backend-down list into an
+EMPTY registry. We build the proxy via the documented lower-level
+pattern — FastMCP + add_provider(ProxyProvider(client_factory,
+cache_ttl=<long>)) — with a 24h cache_ttl so the tool palette survives
+any realistic daemon bounce. (FastMCPProxy hardcodes ProxyProvider with
+no cache_ttl passthrough, so it cannot be used here.) No active
+keepalive: a keepalive cannot help the cold-start-while-down edge, and a
+long TTL covers expiry (YAGNI).
+
+`init_timeout` keeps a down/bouncing daemon from hanging the call: the
+backend connect fails fast and the TransientErrorMiddleware (attached in
+Task 5) turns that into a structured retryable tool result.
+
+Output-schema stripping (spec Amendment 2): a FastMCP ProxyProvider
+mirrors each backend tool's output_schema and the server then
+re-validates every result against it. That would reject the
+TransientErrorMiddleware's {transient:true} payload (it cannot match an
+arbitrary tool's schema) and mangle it into an opaque output-validation
+error. A transparent passthrough proxy must not re-validate the
+backend's own outputs anyway, so _NoOutputSchemaProxyProvider drops the
+output_schema on every proxied tool.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.proxy import ProxyClient, ProxyProvider
+
+from agent_core_busproxy.transient import TransientErrorMiddleware
+
+
+class _NoOutputSchemaProxyProvider(ProxyProvider):
+    """ProxyProvider that drops backend tool output schemas.
+
+    See module docstring (spec Amendment 2). Overrides both the list and
+    single-tool resolution paths so FastMCP performs no output validation
+    on proxied results — letting the transient payload AND normal
+    passthrough results through unchanged.
+    """
+
+    @staticmethod
+    def _strip(tool: Any) -> Any:
+        # Any: avoid annotating with fastmcp's non-public Tool internals.
+        if tool is None:
+            return None
+        return tool.model_copy(update={"output_schema": None})
+
+    async def _list_tools(self) -> Any:
+        return [self._strip(t) for t in await super()._list_tools()]
+
+    async def _get_tool(self, name: str, version: Any = None) -> Any:
+        return self._strip(await super()._get_tool(name, version))
+
+# Fail-fast: a down daemon must not hang a tool call. Small connect/init
+# budget; the agent owns the retry decision (spec: fail-fast retryable).
+_BACKEND_INIT_TIMEOUT_SECONDS = 5.0
+# Per-call request budget once connected (a healthy daemon answers in ms;
+# this only bounds a half-open connection).
+_BACKEND_REQUEST_TIMEOUT_SECONDS = 60.0
+# Tool-list cache lifetime. Long enough that the palette survives any
+# realistic daemon bounce/refresh within a session (spec Amendment).
+_TOOL_CACHE_TTL_SECONDS = 86400.0
+
+
+def build_busproxy(
+    *,
+    agent: str,
+    daemon_url: str | None,
+    _backend: Any | None = None,
+) -> FastMCP:
+    """Return a FastMCP proxy over the daemon's per-agent endpoint.
+
+    Args:
+        agent: bus agent name (URL path segment).
+        daemon_url: e.g. ``http://127.0.0.1:8789``. Ignored when
+            ``_backend`` is supplied.
+        _backend: test seam — an in-process FastMCP server to proxy
+            instead of an HTTP URL. Production always passes a URL.
+    """
+    if _backend is not None:
+        base_client = ProxyClient(_backend)
+    else:
+        if not daemon_url:
+            raise ValueError("daemon_url is required when no _backend is given")
+        url = f"{daemon_url.rstrip('/')}/mcp/{agent}"
+        base_client = ProxyClient(
+            url,
+            init_timeout=_BACKEND_INIT_TIMEOUT_SECONDS,
+            timeout=_BACKEND_REQUEST_TIMEOUT_SECONDS,
+        )
+
+    # -> Any: ProxyClient.new() returns an httpx-backed client (URL path)
+    # or an in-process FastMCP client (_backend path) — undifferentiated.
+    def client_factory() -> Any:
+        # Fresh session per request — the #91 fix.
+        return base_client.new()
+
+    proxy = FastMCP(name=f"agent-core[{agent}]")
+    proxy.add_provider(
+        _NoOutputSchemaProxyProvider(
+            client_factory, cache_ttl=_TOOL_CACHE_TTL_SECONDS
+        )
+    )
+    # daemon_url is the middleware's liveness-probe target. None on the
+    # in-process test path => probing disabled (ambiguous => genuine).
+    proxy.add_middleware(TransientErrorMiddleware(daemon_url=daemon_url))
+    return proxy

agent_core_busproxy/transient.py

@@ -0,0 +1,148 @@
+"""Translate backend-unreachable failures into a structured, retryable
+tool result. Genuine backend tool errors pass through verbatim so the
+agent never retry-loops on a real failure.
+
+Two backend-down shapes (spec Amendment 2026-05-16):
+  1. Transport error — warm tool cache, per-request connect to the dead
+     daemon fails. Unambiguously transient.
+  2. NotFoundError("Unknown tool: ...") — the tool-list fetch failed and
+     FastMCP's ProxyProvider/AggregateProvider swallowed it into an empty
+     registry. AMBIGUOUS: identical shape to a genuine unknown-tool / tool
+     exception from a HEALTHY daemon. Disambiguated with a fast TCP
+     liveness probe to the daemon: unreachable => transient; reachable =>
+     genuine, re-raised unchanged.
+
+     NOTE: fastmcp raises `NotFoundError` server-side from
+     `FastMCP.call_tool` when the resolved tool list is empty (backend-down
+     → swallowed list → empty registry). ToolError is also classified
+     AMBIGUOUS for forward-compatibility with versions that may change this
+     behaviour.
+
+Unknown exception types are treated as genuine — a real bug is never
+masked as retryable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from enum import Enum
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.server.middleware import Middleware
+from fastmcp.tools.base import ToolResult
+from mcp.shared.exceptions import McpError
+
+log = logging.getLogger(__name__)
+
+TRANSIENT_ERROR_CODE = "bus_unavailable"
+_RETRY_AFTER_SECONDS = 5
+_PROBE_TIMEOUT_SECONDS = 2.0
+
+# Reuse the #76 redaction shape: drop the entire query string (signed CDN
+# tokens / session ids live there).
+_URL_QS_RE = re.compile(r"(https?://[^\s?]+)\?\S*")
+
+
+def redact(text: str) -> str:
+    """Strip query strings from any URLs in a human string."""
+    return _URL_QS_RE.sub(r"\1?<redacted>", text)
+
+
+class Disposition(Enum):
+    """How a backend exception should be handled."""
+
+    TRANSIENT = "transient"  # definitely daemon unreachable
+    GENUINE = "genuine"  # definitely a real error — re-raise
+    AMBIGUOUS = "ambiguous"  # could be either — probe the daemon to decide
+
+
+# Transport-class: could not reach / handshake the daemon. Definitely
+# transient. (NotFoundError/ToolError are NOT in here — ambiguous, handled below.)
+_TRANSIENT_TYPES: tuple[type[BaseException], ...] = (
+    httpx.HTTPError,
+    ConnectionError,
+    TimeoutError,
+    OSError,
+    McpError,
+)
+
+
+def classify_backend_error(exc: BaseException) -> Disposition:
+    """Triage a backend exception (see module docstring)."""
+    if isinstance(exc, _TRANSIENT_TYPES):
+        return Disposition.TRANSIENT
+    # NotFoundError: fastmcp raises this (not ToolError) from FastMCP.call_tool
+    # when the resolved tool list is empty (backend-down → swallowed list →
+    # empty registry). ToolError: kept for forward-compatibility.
+    if isinstance(exc, (NotFoundError, ToolError)):
+        return Disposition.AMBIGUOUS
+    return Disposition.GENUINE
+
+
+async def daemon_reachable(daemon_url: str) -> bool:
+    """Fast TCP liveness probe — can we open a socket to the daemon?
+
+    A bounced/down daemon has nothing listening on its port, so a refused
+    or timed-out connect means 'down'. Bounded by _PROBE_TIMEOUT_SECONDS
+    so it cannot itself hang a tool call.
+    """
+    parsed = urlparse(daemon_url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 80
+    try:
+        fut = asyncio.open_connection(host, port)
+        _reader, writer = await asyncio.wait_for(
+            fut, timeout=_PROBE_TIMEOUT_SECONDS
+        )
+    except (TimeoutError, OSError):
+        return False
+    writer.close()
+    try:
+        await writer.wait_closed()
+    except Exception:  # close best-effort
+        pass
+    return True
+
+
+def _transient_result(exc: BaseException) -> ToolResult:
+    detail = redact(f"{type(exc).__name__}: {exc}")
+    log.warning("busproxy: backend unavailable (transient): %s", detail)
+    return ToolResult(
+        structured_content={
+            "error": TRANSIENT_ERROR_CODE,
+            "transient": True,
+            "retry_after_seconds": _RETRY_AFTER_SECONDS,
+            "detail": detail,
+        }
+    )
+
+
+class TransientErrorMiddleware(Middleware):
+    """Map daemon-unreachable to a retryable result; pass real errors through.
+
+    ``daemon_url`` is the liveness-probe target. ``None`` (the in-process
+    test path) disables probing — an AMBIGUOUS error is then treated as
+    genuine so a real error is never masked when we cannot verify.
+    """
+
+    def __init__(self, daemon_url: str | None = None) -> None:
+        self._daemon_url = daemon_url
+
+    async def on_call_tool(self, context: Any, call_next: Any) -> ToolResult:
+        try:
+            return await call_next(context)
+        except BaseException as exc:  # triage then re-raise (never swallow)
+            disposition = classify_backend_error(exc)
+            if disposition is Disposition.TRANSIENT:
+                return _transient_result(exc)
+            if disposition is Disposition.AMBIGUOUS and (
+                self._daemon_url is not None
+                and not await daemon_reachable(self._daemon_url)
+            ):
+                return _transient_result(exc)
+            raise

agent_core_busproxy-0.8.1.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agent-core-busproxy
+Version: 0.8.1
+Summary: Stdio MCP proxy — bridges Claude Code to the agent-core daemon bus tool surface with per-request backend sessions so a daemon bounce never strands the session.
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: fastmcp>=3.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: typer>=0.12

agent_core_busproxy-0.8.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+agent_core_busproxy/__init__.py,sha256=HZ3dTcOuviHe3H81tZ29Zv8CgvTDgEo86PptF_VJdls,78
+agent_core_busproxy/__main__.py,sha256=tuHNcvQ1A7xwoLVFijJ8jIYc2UD17cR0hn6HiswwOgU,948
+agent_core_busproxy/proxy.py,sha256=lWgGwbQRKhzk611TJLwuTCWRmoOZ_AJU4dMyDEHWYWo,4809
+agent_core_busproxy/transient.py,sha256=jrU1MdcxcyFrIHonEOiu-cMJLCze_IVSM2aIty8DNtA,5355
+agent_core_busproxy-0.8.1.dist-info/METADATA,sha256=bs2MNEad-xEJC-WbzvxNBow5j2vVXROFVJBcsc51A4o,414
+agent_core_busproxy-0.8.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_core_busproxy-0.8.1.dist-info/entry_points.txt,sha256=7KUtxYhTxHwQ7hVfPpYZdY4D_bRg7MIrQZjv0J2xLz4,73
+agent_core_busproxy-0.8.1.dist-info/RECORD,,

agent_core_busproxy-0.8.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_core_busproxy-0.8.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-core-busproxy = agent_core_busproxy.__main__:app