agent-core-busproxy 0.9.0__tar.gz

agent_core_busproxy-0.9.0/.gitignore

@@ -0,0 +1,248 @@
+# Memory compiler runtime state
+memory-compiler/daily/
+memory-compiler/reports/
+memory-compiler/scripts/state.json
+memory-compiler/scripts/last-flush.json
+memory-compiler/scripts/flush.log
+memory-compiler/scripts/compile.log
+memory-compiler/scripts/session-flush-*.md
+memory-compiler/scripts/flush-context-*.md
+
+# Handoff writer state (placed alongside handoff files)
+**/handoff-state.json
+
+# Git worktrees (superpowers / parallel feature work)
+.worktrees/
+# Native (harness) worktrees
+.claude/worktrees/
+
+# Superpowers brainstorm mockups / scratch
+.superpowers/
+
+# Agent-core runtime state (handoffs, bus.sqlite, transcripts, etc.)
+.agent-core/
+
+# Local scratch / smoke-test artifacts
+.tmp/
+
+# Claude Code per-machine local overrides
+.claude/settings.local.json
+.claude/*.lock
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+# ...but agent_core.venv is a SOURCE package, not a virtualenv — don't ignore it.
+!packages/core/src/agent_core/venv/
+!packages/core/src/agent_core/venv/**
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.gstack/
+
+# macOS Finder metadata (occasionally sneaks in via vendored sources)
+.DS_Store
+
+# Operational docs that must not live in source control
+pepper-vault-plan.txt

agent_core_busproxy-0.9.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.9.0](https://github.com/jeffrichley/agent_core/compare/v0.8.1...agent-core-busproxy-v0.9.0) (2026-08-03)
+
+
+### Features
+
+* **mypy:** enable --strict for briefs, busproxy, inbound, voice, webcam, qa ([#532](https://github.com/jeffrichley/agent_core/issues/532)) ([9663d87](https://github.com/jeffrichley/agent_core/commit/9663d8783176116a7ae352b2ba07933bf056fbe7))
+
+
+### Bug Fixes
+
+* republish package family to complete rate-limited first publish ([#477](https://github.com/jeffrichley/agent_core/issues/477)) ([32977ac](https://github.com/jeffrichley/agent_core/commit/32977ac78da4a15553329bb4e1fdaa9e894834ad))
+
+## [0.8.1](https://github.com/jeffrichley/agent_core/compare/v0.8.0...agent-core-busproxy-v0.8.1) (2026-07-22)
+
+
+### Bug Fixes
+
+* republish package family to complete rate-limited first publish ([#477](https://github.com/jeffrichley/agent_core/issues/477)) ([32977ac](https://github.com/jeffrichley/agent_core/commit/32977ac78da4a15553329bb4e1fdaa9e894834ad))
+
+## [0.8.0](https://github.com/jeffrichley/agent_core/compare/v0.7.0...agent-core-busproxy-v0.8.0) (2026-07-21)
+
+
+### Features
+
+* **hatchery:** ungendered templates + .mcp.json generation ([#81](https://github.com/jeffrichley/agent_core/issues/81)/[#82](https://github.com/jeffrichley/agent_core/issues/82)) ([#357](https://github.com/jeffrichley/agent_core/issues/357)) ([f48762d](https://github.com/jeffrichley/agent_core/commit/f48762df78eb12cfa9524e9b5a277741534ea8a7)), closes [#311](https://github.com/jeffrichley/agent_core/issues/311)
+* **release:** configure release-please for 12-package synchronized version train ([#428](https://github.com/jeffrichley/agent_core/issues/428)) ([c1b4097](https://github.com/jeffrichley/agent_core/commit/c1b409765c61d09a6657b0e8b5e43a27cb235b3e))

agent_core_busproxy-0.9.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agent-core-busproxy
+Version: 0.9.0
+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.9.0/VERSION

@@ -0,0 +1 @@
+0.9.0

agent_core_busproxy-0.9.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "agent-core-busproxy"
+dynamic = ["version"]
+description = "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 = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=3.2",
+    "mcp>=1.0",
+    "anyio>=4.0",
+    "httpx>=0.27",
+    "typer>=0.12",
+]
+
+[project.scripts]
+agent-core-busproxy = "agent_core_busproxy.__main__:app"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_core_busproxy"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]

agent_core_busproxy-0.9.0/src/agent_core_busproxy/__init__.py

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

agent_core_busproxy-0.9.0/src/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-0.9.0/src/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-0.9.0/src/agent_core_busproxy/transient.py

@@ -0,0 +1,149 @@
+"""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:
+            result: ToolResult = await call_next(context)
+            return result
+        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.9.0/tests/_backend_server.py

@@ -0,0 +1,40 @@
+"""Disposable test backend for the #91 subprocess regression.
+
+Run as: ``python _backend_server.py <port>``. Serves ONE throwaway
+``ClaudeCodeMCPEndpoint`` via the production ``HTTPHost`` on
+``127.0.0.1:<port>`` until the process is killed. This is NOT shipped
+(lives under tests/) and never touches the real daemon — the regression
+always passes an OS-assigned free port and kills only this child.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agent_core.bus.http_host import HTTPHost
+from agent_core.endpoints.claude_code_mcp import ClaudeCodeMCPEndpoint
+
+
+class _StubHandle:
+    async def ack(self, envelope_id: str) -> None: ...
+    async def publish(self, envelope, to=None) -> None: ...
+    async def nack(self, envelope_id, requeue=True) -> None: ...
+    def endpoints(self) -> list:
+        return [type("E", (), {"name": "discord", "description": "d"})()]
+
+
+async def _main(port: int) -> None:
+    ep = ClaudeCodeMCPEndpoint(name="agent", mount="/mcp/agent")
+    await ep.start(_StubHandle())  # type: ignore[arg-type]
+    host = HTTPHost(bind_host="127.0.0.1", bind_port=port)
+    host.mount(ep)
+    await host.start()
+    # Readiness is observed by the parent via a TCP port-probe (this
+    # process's stdout is discarded), so nothing to emit here.
+    # Serve until the parent kills this process (faithful daemon death).
+    await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(_main(int(sys.argv[1])))

agent_core_busproxy-0.9.0/tests/test_cli.py

@@ -0,0 +1,35 @@
+"""Smoke tests for the busproxy Typer CLI."""
+
+from __future__ import annotations
+
+import re
+
+from agent_core_busproxy.__main__ import app
+from typer.testing import CliRunner
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _norm(text: str) -> str:
+    """Strip ANSI escape codes and collapse whitespace.
+
+    Typer/Rich splits option tokens with ANSI style spans under CI
+    (no COLUMNS, non-tty), so raw substring checks are unreliable.
+    """
+    return re.sub(r"\s+", " ", _ANSI_RE.sub("", text))
+
+
+def test_cli_help_runs() -> None:
+    result = CliRunner().invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "--agent" in _norm(result.output)
+    assert "--daemon-url" in _norm(result.output)
+
+
+def test_cli_requires_agent() -> None:
+    result = CliRunner().invoke(app, [])
+    assert result.exit_code != 0
+    assert (
+        "Missing option" in result.output
+        or "required" in result.output.lower()
+    )

agent_core_busproxy-0.9.0/tests/test_down_window.py

@@ -0,0 +1,31 @@
+"""Daemon-down window: a tool call returns the structured transient
+result PROMPTLY (fail-fast, no long hang)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from agent_core_busproxy.proxy import build_busproxy
+from agent_core_busproxy.transient import TRANSIENT_ERROR_CODE
+from fastmcp import Client
+
+# Real connect to a dead port (waits out the connection failure) — slow by
+# nature, so keep it out of the default fast lane. See the `slow` marker
+# definition in pyproject.toml.
+pytestmark = pytest.mark.slow
+
+
+@pytest.mark.asyncio
+async def test_dead_backend_returns_transient_result_fast() -> None:
+    # Nothing listening on 65535 => connect refused/timeout.
+    proxy = build_busproxy(agent="agent", daemon_url="http://127.0.0.1:65535")
+
+    async with Client(proxy) as c:
+        # Whole call must finish well under the 5s init budget * slack.
+        result = await asyncio.wait_for(
+            c.call_tool("list_endpoints", {}), timeout=15.0
+        )
+
+    assert result.structured_content["error"] == TRANSIENT_ERROR_CODE
+    assert result.structured_content["transient"] is True

agent_core_busproxy-0.9.0/tests/test_proxy_api_contract.py

@@ -0,0 +1,121 @@
+"""Pin the installed FastMCP proxy API surface this package depends on.
+
+If FastMCP changes these, this test fails first and points at exactly
+what to update in proxy.py / transient.py.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+import pytest
+
+
+def test_fastmcpproxy_and_proxyclient_importable() -> None:
+    from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+    # FastMCPProxy takes a client_factory kwarg.
+    sig = inspect.signature(FastMCPProxy.__init__)
+    assert "client_factory" in sig.parameters
+
+    # ProxyClient accepts a URL string target and supports .new().
+    pc = ProxyClient("http://127.0.0.1:65535/mcp/nobody")
+    assert hasattr(pc, "new")
+
+
+def test_client_supports_init_timeout() -> None:
+    from fastmcp import Client
+
+    sig = inspect.signature(Client.__init__)
+    assert "init_timeout" in sig.parameters
+
+
+def test_middleware_has_on_call_tool() -> None:
+    from fastmcp.server.middleware import Middleware
+
+    assert hasattr(Middleware, "on_call_tool")
+
+
+def test_toolresult_accepts_structured_content() -> None:
+    from fastmcp.tools.base import ToolResult
+
+    r = ToolResult(structured_content={"error": "x", "transient": True})
+    assert r.structured_content == {"error": "x", "transient": True}
+
+
+@pytest.mark.asyncio
+async def test_client_surfaces_structured_content_attribute() -> None:
+    """Pin the CLIENT-side accessor: a tool returning ToolResult(
+    structured_content=...) is readable as result.structured_content.
+    Every later test asserts on this attribute.
+
+    NOTE: The inner tool function deliberately omits a return-type annotation.
+    Using ``-> ToolResult`` with ``from __future__ import annotations`` (PEP 563)
+    causes pydantic to evaluate it as a forward-reference against the *module*
+    globalns, where the name ``ToolResult`` is absent (the import lives only in
+    the test-function locals).  Omitting the annotation is equivalent for the
+    purpose of this characterization test.
+    """
+    from fastmcp import Client, FastMCP
+    from fastmcp.tools.base import ToolResult
+
+    srv = FastMCP("pin")
+
+    @srv.tool()
+    async def t():  # no return annotation — see docstring
+        return ToolResult(structured_content={"transient": True})
+
+    async with Client(srv) as c:
+        res = await c.call_tool("t", {})
+
+    assert res.structured_content == {"transient": True}
+
+
+@pytest.mark.slow  # real connect to a dead port; see slow marker in pyproject.toml
+@pytest.mark.asyncio
+async def test_dead_backend_raises_on_tool_call() -> None:
+    """Calling a tool through a proxy whose backend is unreachable raises.
+
+    Records the concrete exception type so transient.py can catch it.
+    Port 65535 with nothing listening => connect failure.
+    """
+    from fastmcp import Client
+    from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+    base = ProxyClient("http://127.0.0.1:65535/mcp/nobody", init_timeout=2.0)
+    proxy = FastMCPProxy(client_factory=lambda: base.new(), name="probe")
+
+    with pytest.raises(BaseException) as excinfo:  # broad: characterizing
+        async with Client(proxy) as c:
+            await c.call_tool("list_endpoints", {})
+
+    # Concrete type pinned for transient.classify_backend_error.
+    # Assert it is NOT a clean MCP tool-result (i.e. the failure surfaces
+    # as an exception, which is what the middleware will intercept).
+    assert excinfo.value is not None
+    chain = []
+    e: BaseException | None = excinfo.value
+    while e is not None:
+        chain.append(type(e).__name__)
+        e = e.__cause__ or e.__context__
+    # Connection-class failure somewhere in the chain.
+    #
+    # OBSERVED BEHAVIOUR (fastmcp 3.2.2): AggregateProvider._collect_list_results
+    # absorbs the actual connect error during list_tools() (logs a WARNING) and
+    # returns an empty tool list.  A subsequent call_tool() therefore fails with
+    # ToolError("Unknown tool: '...'") — never a raw connection exception.
+    # transient.classify_backend_error must therefore match "ToolError" (in
+    # addition to raw transport errors that could surface in other code-paths).
+    assert any(
+        n in chain
+        for n in (
+            "ToolError",
+            "ConnectError",
+            "ConnectionError",
+            "ConnectTimeout",
+            "McpError",
+            "HTTPError",
+            "OSError",
+            "TimeoutError",
+        )
+    ), f"unexpected exception chain: {chain}"

agent_core_busproxy-0.9.0/tests/test_proxy_build.py

@@ -0,0 +1,52 @@
+"""build_busproxy assembles a proxy that mirrors the daemon tool surface."""
+
+from __future__ import annotations
+
+import pytest
+from agent_core_busproxy.proxy import build_busproxy
+from fastmcp import Client
+
+from agent_core.endpoints.claude_code_mcp import ClaudeCodeMCPEndpoint
+
+
+class _StubHandle:
+    async def ack(self, envelope_id: str) -> None: ...
+    async def publish(self, envelope, to=None) -> None: ...
+    async def nack(self, envelope_id, requeue=True) -> None: ...
+    def endpoints(self) -> list:
+        return []
+
+
+# The bus tool surface ClaudeCodeMCPEndpoint guarantees (see
+# claude_code_mcp.py _register_tools). Asserting these by name avoids
+# depending on any FastMCP-internal tool-enumeration API.
+_EXPECTED_BUS_TOOLS = {
+    "send",
+    "list_endpoints",
+    "describe_endpoint",
+    "list_pending",
+    "handle",
+    "ack",
+    "nack",
+    "consume",
+    "reply",
+    "peek",
+    "show_my_day",
+}
+
+
+@pytest.mark.asyncio
+async def test_proxy_mirrors_backend_tool_surface() -> None:
+    """tools/list through the proxy exposes the daemon endpoint's tools."""
+    backend = ClaudeCodeMCPEndpoint(name="agent", mount="/mcp/agent")
+    await backend.start(_StubHandle())  # type: ignore[arg-type]
+    try:
+        # Proxy pointed directly at the in-process backend server.
+        proxy = build_busproxy(agent="agent", daemon_url=None, _backend=backend._mcp)
+        async with Client(proxy) as c:
+            proxied = {t.name for t in await c.list_tools()}
+
+        missing = _EXPECTED_BUS_TOOLS - proxied
+        assert not missing, f"proxy missing bus tools: {missing}"
+    finally:
+        await backend.stop()

agent_core_busproxy-0.9.0/tests/test_regression_daemon_bounce.py

@@ -0,0 +1,180 @@
+"""#91 regression: a daemon restart must not strand a live session.
+
+A single long-lived busproxy Client stays connected across a full
+daemon bounce. Because every tool call mints a fresh backend session,
+the post-restart call recovers without any client re-initialize.
+
+The backend runs as a real SEPARATE PROCESS on an OS-assigned free port
+(never the real daemon's port) so killing it and starting a fresh one is
+a faithful daemon bounce (process dies → new process binds the port),
+free of in-process event-loop/lifespan races. The test only ever kills
+its own child process.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+from agent_core_busproxy.proxy import build_busproxy
+from fastmcp import Client
+
+_BACKEND = Path(__file__).parent / "_backend_server.py"
+
+# Both tests spawn real backend subprocesses (cold Python + fastmcp import +
+# socket bind) — slow by nature, so keep them out of the default fast lane.
+# See the `slow` marker definition in pyproject.toml.
+pytestmark = pytest.mark.slow
+
+
+def _free_port() -> int:
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+async def _port_open(port: int) -> bool:
+    try:
+        fut = asyncio.open_connection("127.0.0.1", port)
+        _r, w = await asyncio.wait_for(fut, timeout=1.0)
+    except (TimeoutError, OSError):
+        return False
+    w.close()
+    return True
+
+
+async def _spawn_backend(port: int, *, script: Path = _BACKEND) -> subprocess.Popen:
+    """Start the disposable backend subprocess and wait until it listens.
+
+    Readiness budget is generous (30s) because cold Python + fastmcp
+    import + bind is slow on a loaded host — e.g. CI under xdist, or this
+    suite running inside a resource-contended container (the foreman
+    daemon's worker check). The old 10s budget passed on a dedicated
+    runner but flaked under contention, where bind routinely took ~8-10s.
+
+    stderr is captured (not discarded) so a genuine startup *failure*
+    surfaces in the raised error instead of a blind "did not become
+    ready" — the original DEVNULL hid the difference between slow-bind
+    and crash-on-start.
+    """
+    stderr = tempfile.TemporaryFile()
+    proc = subprocess.Popen(
+        [sys.executable, str(script), str(port)],
+        stdout=subprocess.DEVNULL,
+        stderr=stderr,
+    )
+
+    def _captured_stderr() -> str:
+        try:
+            stderr.seek(0)
+            return stderr.read().decode("utf-8", "replace").strip() or "<empty>"
+        except Exception:  # pragma: no cover - diagnostic best-effort
+            return "<unavailable>"
+
+    for _ in range(300):  # ~30s bounded readiness (load-tolerant)
+        if proc.poll() is not None:
+            raise RuntimeError(
+                f"backend exited early (rc={proc.returncode}); "
+                f"stderr:\n{_captured_stderr()}"
+            )
+        if await _port_open(port):
+            return proc
+        await asyncio.sleep(0.1)
+    proc.kill()
+    raise RuntimeError(
+        f"backend did not become ready within 30s; stderr:\n{_captured_stderr()}"
+    )
+
+
+def _kill(proc: subprocess.Popen) -> None:
+    if proc.poll() is not None:
+        return
+    proc.terminate()
+    try:
+        proc.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+
+
+@pytest.mark.asyncio
+async def test_spawn_backend_surfaces_crash_with_stderr(tmp_path: Path) -> None:
+    """A crash-on-start must raise with the cause named AND the stderr text.
+
+    This is the diagnostic the DEVNULL -> TemporaryFile change exists to
+    provide: the old code blindly reported "did not become ready" whether the
+    backend was slow or dead. A backend that writes to stderr and exits
+    non-zero should surface both the exit code and that stderr in the error.
+    """
+    crasher = tmp_path / "crasher.py"
+    crasher.write_text(
+        "import sys\n"
+        "sys.stderr.write('boom: backend refused to start\\n')\n"
+        "sys.exit(3)\n"
+    )
+    with pytest.raises(RuntimeError) as excinfo:
+        await _spawn_backend(_free_port(), script=crasher)
+    message = str(excinfo.value)
+    assert "exited early" in message
+    assert "rc=3" in message
+    assert "boom: backend refused to start" in message
+
+
+# The two internal readiness budgets (spawn #1 + recovery spawn #2) sum to
+# ~60s worst-case, which would collide with the global 60s pytest-timeout and
+# reintroduce the very flake this test guards against. Give a per-test ceiling
+# with real headroom over the worst-case internal sum + spawn/teardown overhead.
+@pytest.mark.timeout(150)
+@pytest.mark.asyncio
+async def test_session_survives_backend_bounce() -> None:
+    port = _free_port()
+    proxy = build_busproxy(agent="agent", daemon_url=f"http://127.0.0.1:{port}")
+
+    backend = await _spawn_backend(port)  # daemon #1 (own child, own port)
+    second: subprocess.Popen | None = None
+    try:
+        async with Client(proxy) as client:  # one long-lived client
+            r1 = await client.call_tool("list_endpoints", {})
+            assert any(e["name"] == "discord" for e in r1.data)
+
+            _kill(backend)  # real daemon bounce: process dies
+            backend = None  # type: ignore[assignment]
+
+            # Daemon-down window: SAME client, no re-handshake → transient.
+            mid = await client.call_tool("list_endpoints", {})
+            assert mid.structured_content["transient"] is True
+
+            # Fresh daemon process on the SAME port (OS released it on the
+            # kill above — no in-process race). The spec contract is
+            # fail-fast + the agent RETRIES on {transient}, so model that:
+            # poll the same client until it recovers, bounded. #91 is the
+            # property that the session *eventually recovers* across the
+            # bounce with no re-handshake.
+            second = await _spawn_backend(port)
+            recovered = False
+            for _ in range(60):  # ~30s bounded retry budget (load-tolerant)
+                try:
+                    res = await client.call_tool("list_endpoints", {})
+                except Exception:
+                    await asyncio.sleep(0.5)
+                    continue
+                sc = res.structured_content
+                if isinstance(sc, dict) and sc.get("transient"):
+                    await asyncio.sleep(0.5)
+                    continue
+                assert any(e["name"] == "discord" for e in res.data)
+                recovered = True
+                break
+            assert recovered, "session did not recover after daemon restart"
+    finally:
+        if backend is not None:
+            _kill(backend)
+        if second is not None:
+            _kill(second)

agent_core_busproxy-0.9.0/tests/test_scaffold.py

@@ -0,0 +1,9 @@
+"""Package scaffold smoke test."""
+
+from __future__ import annotations
+
+
+def test_package_imports() -> None:
+    import agent_core_busproxy
+
+    assert agent_core_busproxy.__doc__ is not None

agent_core_busproxy-0.9.0/tests/test_transient.py

@@ -0,0 +1,167 @@
+"""TransientErrorMiddleware: backend-down -> structured retryable result;
+genuine tool errors pass through verbatim.
+
+Per spec Amendment 2026-05-16: a backend-down failure can surface either
+as a transport error (warm cache, per-request connect fails) OR as a
+ToolError("Unknown tool: ...") (empty registry because the list fetch
+was swallowed). The latter is AMBIGUOUS with a genuine unknown-tool /
+tool exception, so it is disambiguated with a fast daemon liveness probe.
+"""
+
+from __future__ import annotations
+
+import socket
+
+import httpx
+import pytest
+from agent_core_busproxy.transient import (
+    TRANSIENT_ERROR_CODE,
+    Disposition,
+    TransientErrorMiddleware,
+    classify_backend_error,
+    daemon_reachable,
+    redact,
+)
+from fastmcp.exceptions import NotFoundError, ToolError
+
+
+def test_redact_strips_query_string() -> None:
+    # Same discipline as the #76 signed-CDN redaction.
+    assert redact("connect to https://cdn.example.com/x?sig=SECRET&t=9") == (
+        "connect to https://cdn.example.com/x?<redacted>"
+    )
+
+
+def test_classify_transport_error_is_transient() -> None:
+    assert classify_backend_error(httpx.ConnectError("refused")) is Disposition.TRANSIENT
+    assert classify_backend_error(ConnectionError("refused")) is Disposition.TRANSIENT
+    assert classify_backend_error(TimeoutError()) is Disposition.TRANSIENT
+
+
+def test_classify_tool_error_is_ambiguous() -> None:
+    # Could be 'down -> empty registry' OR a real unknown-tool error.
+    assert classify_backend_error(ToolError("Unknown tool: x")) is Disposition.AMBIGUOUS
+
+
+def test_classify_unknown_is_genuine() -> None:
+    # Never mask an unrecognized error as retryable.
+    assert classify_backend_error(ValueError("nope")) is Disposition.GENUINE
+
+
+@pytest.mark.slow  # probes a dead port (waits out the connect failure)
+@pytest.mark.asyncio
+async def test_daemon_reachable_true_and_false() -> None:
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+    host, port = srv.getsockname()
+    try:
+        assert await daemon_reachable(f"http://{host}:{port}") is True
+    finally:
+        srv.close()
+    # Nothing listening on 65535 => not reachable.
+    assert await daemon_reachable("http://127.0.0.1:65535") is False
+
+
+@pytest.mark.asyncio
+async def test_transport_error_becomes_transient_result() -> None:
+    mw = TransientErrorMiddleware(daemon_url="http://127.0.0.1:65535")
+
+    async def call_next(_ctx):
+        raise httpx.ConnectError("Connection refused to http://h/x?token=ABC")
+
+    result = await mw.on_call_tool(object(), call_next)
+
+    assert result.structured_content["error"] == TRANSIENT_ERROR_CODE
+    assert result.structured_content["transient"] is True
+    assert isinstance(result.structured_content["retry_after_seconds"], int)
+    assert "token=ABC" not in result.structured_content["detail"]
+    assert "<redacted>" in result.structured_content["detail"]
+
+
+@pytest.mark.slow  # probes a dead port (waits out the connect failure)
+@pytest.mark.asyncio
+async def test_toolerror_with_daemon_down_becomes_transient() -> None:
+    # 65535 unbound => probe says down => AMBIGUOUS resolves to transient.
+    mw = TransientErrorMiddleware(daemon_url="http://127.0.0.1:65535")
+
+    async def call_next(_ctx):
+        raise ToolError("Unknown tool: 'consume'")
+
+    result = await mw.on_call_tool(object(), call_next)
+    assert result.structured_content["transient"] is True
+
+
+@pytest.mark.asyncio
+async def test_toolerror_with_daemon_up_passes_through() -> None:
+    # A real listening socket => probe says reachable => genuine passthrough.
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+    host, port = srv.getsockname()
+    try:
+        mw = TransientErrorMiddleware(daemon_url=f"http://{host}:{port}")
+
+        async def call_next(_ctx):
+            raise ToolError("envelope_id not found")
+
+        with pytest.raises(ToolError, match="envelope_id not found"):
+            await mw.on_call_tool(object(), call_next)
+    finally:
+        srv.close()
+
+
+@pytest.mark.asyncio
+async def test_no_daemon_url_treats_ambiguous_as_genuine() -> None:
+    # In-process/test path (no URL): cannot probe => do not mask as transient.
+    mw = TransientErrorMiddleware(daemon_url=None)
+
+    async def call_next(_ctx):
+        raise ToolError("envelope_id not found")
+
+    with pytest.raises(ToolError, match="envelope_id not found"):
+        await mw.on_call_tool(object(), call_next)
+
+
+def test_classify_not_found_error_is_ambiguous() -> None:
+    # fastmcp 3.2.4 raises NotFoundError (NOT ToolError) server-side for an
+    # empty-registry unknown tool — the #91 backend-down path the proxy's
+    # middleware actually sees. Must be AMBIGUOUS so the liveness probe can
+    # disambiguate down-daemon vs a genuinely missing tool.
+    assert (
+        classify_backend_error(NotFoundError("Unknown tool: 'x'"))
+        is Disposition.AMBIGUOUS
+    )
+
+
+@pytest.mark.slow  # probes a dead port (waits out the connect failure)
+@pytest.mark.asyncio
+async def test_not_found_error_with_daemon_down_becomes_transient() -> None:
+    mw = TransientErrorMiddleware(daemon_url="http://127.0.0.1:65535")
+
+    async def call_next(_ctx):
+        raise NotFoundError("Unknown tool: 'consume'")
+
+    result = await mw.on_call_tool(object(), call_next)
+    assert result.structured_content["transient"] is True
+
+
+@pytest.mark.asyncio
+async def test_not_found_error_with_daemon_up_passes_through() -> None:
+    # The no-masking guarantee for the exact exception that motivated the
+    # Task 5 deviation: a genuinely-missing tool on a HEALTHY daemon must
+    # re-raise, never be masked as a retryable transient result.
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+    host, port = srv.getsockname()
+    try:
+        mw = TransientErrorMiddleware(daemon_url=f"http://{host}:{port}")
+
+        async def call_next(_ctx):
+            raise NotFoundError("Unknown tool: 'genuinely_missing'")
+
+        with pytest.raises(NotFoundError, match="genuinely_missing"):
+            await mw.on_call_tool(object(), call_next)
+    finally:
+        srv.close()