Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions ADAPTER_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,3 +130,17 @@ retry is logged as `gate refused; retried with all N tools aliased`.
- Offline: the adapter unit and proxy tests in each repository, against a fake upstream.
- Live: start the adapter against `https://api.meta.ai`, send a request with a colliding tool
name, and require HTTP 200 with the original name restored in the response.

## Diagnostics (outside the wire rules)

`GET /__muse_adapter/health` answers before the relay rules with
`{adapter_version, pid, port, passthrough, upstream}`, and every relayed response carries
`x-muse-adapter: <ADAPTER_VERSION>`. Both exist so a caller can tell whether a captured request
went through an adapter at all and, when it did, whether that adapter is the one this process
started: a port can be held by an adapter from an older plugin, by another process, or by
something unrelated.

These additions do not change any rule above, so `ADAPTER_VERSION` stays at 3. A refused request
(HTTP 400 or above) also logs one line at the host's warning level with the method, path, status,
adapter version, port, pid and the rules that fired. Neither the log line nor the health answer
carries a request body, a response body, or a credential.
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,28 @@ All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Fixed

- The loopback wire adapter starts on first use instead of at import. Loading the plugin without
running inference (the admission probe, `hermes plugins validate`, a linter) no longer binds a
port, and `register()` no longer starts one either. Those probes exit immediately and used to
leave the listener behind, so the next process bound the following port and every process
reported a different base URL.
- `runtime_base_url()` resolves the adapter on demand, so a process that never imported the plugin
at startup still gets its own loopback adapter when Hermes resolves the credential.

### Added

- `GET /__muse_adapter/health` reports `adapter_version`, `pid`, `port`, `passthrough` and
`upstream`, and `python muse_adapter.py --health <url>` queries it. An adapter that cannot answer
belongs to another process or to a plugin older than this release, which is what makes a stale
loopback port diagnosable.
- Every relayed response carries `x-muse-adapter: <version>`.
- A refused request (status 400 or above) logs one warning line with the method, path, upstream
status, adapter version, port and pid, and the rules that fired. No body and no credential.

## [0.6.4] - 2026-11-12

### Fixed
Expand Down
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,25 @@ Signing in again cannot remove a client restriction (the key is not expired). Us
the subscription, or a separate pay-as-you-go Meta Model API key for other clients, subject to
Meta's terms.

### Requests fail with "authentication failed"

On hosts older than 0.23 a refused request and a bad key reach the user with the same
`authentication failed` text: the 403 `client_attestation_denied` is not classified separately
until 0.23. Do not re-login first; check which adapter answered.

The adapter starts on first use, and every process owns its own instance, so a loopback port
reported by one process is not necessarily the one in use now. Ask the port directly:

```bash
python muse_adapter.py --health http://127.0.0.1:43219/v1
```

It prints `adapter_version`, `pid`, `port`, `passthrough` and `upstream`, or says that no adapter
answered. A port held by an adapter without this answer belongs to another process or to an older
plugin, and that process is not the one serving the request. Every relayed response also
carries `x-muse-adapter: <version>`, and each refused request logs one warning line with the method,
path, upstream status, adapter version, port and pid, but no body and no credential.

### The gateway keeps the old key

Since 0.6.4 the provider reads the cache when Hermes resolves the credential, so a completed login
Expand Down
36 changes: 24 additions & 12 deletions __init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,11 +126,16 @@ def _adapter_base_url() -> str:
imports and registrations reuse the same server. If no loopback port can be
bound, keep the direct endpoint (the pre-0.6 behavior) and warn: only the
exception type is logged, never credentials or payloads.

Called lazily, never at import: a short-lived process that only loads the
plugin (the admission probe, ``hermes plugins validate``, a linter) must not
bind a loopback port. Each process owns its adapter on the first free port,
so an adapter left behind by another process is never adopted as this one's.
"""
if _start_adapter is None:
return DEFAULT_BASE_URL
try:
adapter = _start_adapter(log=logger.debug)
adapter = _start_adapter(log=logger.debug, error_log=logger.warning)
except Exception as error: # noqa: BLE001 - a bind failure must not break import
logger.warning(
"Muse Code wire adapter unavailable (%s); using %s directly",
Expand All @@ -151,14 +156,15 @@ def _refresh_base_url() -> None:
def register(ctx) -> None:
"""PluginManager entry point (also required by `hermes plugins validate`).

Provider registration already happened at import; re-read the cache so
a login that completed after import is picked up, and retry the wire
adapter in case the first bind failed. Stdlib-only, so the admission probe
can run it in a bare interpreter.
Provider registration already happened at import; re-read the cache so a
login that completed after import is picked up. The wire adapter is started
on first use (``runtime_base_url``) rather than here: validation and
admission probes run this hook in a bare interpreter that then exits, and
an adapter started here would outlive the probe on a loopback port. Stdlib
only, so those probes can still run it.
"""
if _HERMES_AVAILABLE:
_ensure_subscription_key()
_refresh_base_url()


# Meta Model API (Muse) wire vocabulary, vendored from Hermes core
Expand Down Expand Up @@ -254,10 +260,12 @@ def runtime_base_url(

Runtime credential resolution only reads this hook, so without the
override ``base_url`` is never consulted: requests go straight to
``api.meta.ai`` and Meta answers 403. ``register()`` keeps
``self.base_url`` on the adapter, or on the direct endpoint when the
adapter could not bind.
``api.meta.ai`` and Meta answers 403. Resolution is also the first
moment the adapter is actually needed, so it starts here (idempotent
per process) instead of at import; ``self.base_url`` then holds that
adapter's URL, or the direct endpoint when no port could be bound.
"""
_refresh_base_url()
return self.base_url or None

def resolve_api_key_secret(self) -> tuple[str, str] | None:
Expand Down Expand Up @@ -287,6 +295,9 @@ def fetch_models(
timeout: float = 8.0,
) -> list[str] | None:
_ensure_subscription_key()
# Discovery is a GET, which the adapter relays untouched, and Meta
# serves /v1/models directly (verified with a subscription key), so
# it does not need the loopback hop or a port binding.
live = super().fetch_models(
api_key=api_key, base_url=base_url, timeout=timeout
)
Expand Down Expand Up @@ -320,9 +331,10 @@ def build_api_kwargs_extras(
description="Muse chat models billed to the local Muse Code monthly login",
signup_url="https://github.com/TheStreamCode/hermes-muse-code#login-once",
env_vars=(ENV_VAR,),
# Loopback wire adapter in front of api.meta.ai; DEFAULT_BASE_URL when
# the adapter could not bind and the provider runs direct.
base_url=_adapter_base_url(),
# Loopback wire adapter in front of api.meta.ai; started on first
# resolution (see runtime_base_url), DEFAULT_BASE_URL until then or when
# no port could be bound and the provider runs direct.
base_url=DEFAULT_BASE_URL,
auth_type="api_key",
auth_handler=_auth_handler,
classify_api_error=_classify_client_restriction,
Expand Down
116 changes: 114 additions & 2 deletions muse_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,11 @@
# Ports tried in order, so a persisted base URL stays stable across restarts.
DEFAULT_PORTS = (43219, 43220, 43221, 43222)

# Diagnostic endpoint. It answers before the relay rules, so a caller can tell
# which adapter owns a port: this process' adapter, a stale one from an older
# plugin, or something else entirely. Not part of the wire contract.
HEALTH_PATH = "/__muse_adapter/health"

_JsonRecord = dict[str, Any]


Expand Down Expand Up @@ -412,6 +417,7 @@ class _AdapterConfig:
upstream: str
passthrough: bool
log: Callable[[str], None] | None
error_log: Callable[[str], None] | None = None


class _AdapterServer(http.server.ThreadingHTTPServer):
Expand Down Expand Up @@ -443,6 +449,22 @@ def _log(config: _AdapterConfig, message: str) -> None:
pass


def _log_error(config: _AdapterConfig, message: str) -> None:
"""Report a failed request at the host's warning level.

A refused request must be visible without the caller turning on debug
logging: Meta's errors reach the caller as a bare "authentication failed",
and this line is the only place that records the upstream status and which
adapter answered. It never carries request or response bodies.
"""
if config.error_log is None:
return
try:
config.error_log(message)
except Exception: # noqa: BLE001 - diagnostics must never break a request
pass


class _AdapterHandler(http.server.BaseHTTPRequestHandler):
"""One proxied request: adapt the request, relay the answer, restore names."""

Expand All @@ -462,8 +484,34 @@ def handle_expect_100(self) -> bool:
return True

def do_GET(self) -> None: # noqa: N802 - stdlib handler naming
if urllib.parse.urlsplit(self.path).path == HEALTH_PATH:
self._serve_health()
return
self._handle()

def _serve_health(self) -> None:
"""Report which adapter this is, without touching upstream or credentials."""
config: _AdapterConfig = self.server.config # type: ignore[attr-defined]
payload = json.dumps(
{
"adapter_version": ADAPTER_VERSION,
"pid": os.getpid(),
"port": int(self.server.server_address[1]), # type: ignore[attr-defined]
"passthrough": config.passthrough,
"upstream": config.upstream,
},
separators=(",", ":"),
).encode("utf-8")
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(payload)))
self.send_header("x-muse-adapter", str(ADAPTER_VERSION))
self.end_headers()
try:
self.wfile.write(payload)
except (BrokenPipeError, ConnectionResetError):
self.close_connection = True

def do_POST(self) -> None: # noqa: N802 - stdlib handler naming
self._handle()

Expand All @@ -484,7 +532,7 @@ def _handle(self) -> None:
self.close_connection = True
except Exception as error: # noqa: BLE001 - one bad request must not kill the server
config: _AdapterConfig = self.server.config # type: ignore[attr-defined]
_log(config, f"muse-code adapter error: {type(error).__name__}: {error}")
_log_error(config, f"muse-code adapter error: {type(error).__name__}: {error}")
if not self._headers_sent:
payload = json.dumps(_ADAPTER_ERROR).encode("utf-8")
try:
Expand Down Expand Up @@ -650,7 +698,18 @@ def send(payload: bytes) -> Any:
raw_headers = getattr(upstream, "headers", None)
headers = raw_headers if raw_headers is not None else {}
content_type = str(headers.get("content-type") or "").lower()
if notes:
if int(status) >= 400:
# One line per refused request, at warning level: the caller only
# sees the provider's generic message, so this is the record of
# which adapter answered and what upstream returned.
rules = ", ".join(notes) if notes else "no rule fired"
_log_error(
config,
f"muse-code adapter: {method} {pathname} {status}"
f" | v{ADAPTER_VERSION} port={int(self.server.server_address[1])}" # type: ignore[attr-defined]
f" pid={os.getpid()} | {rules}",
)
elif notes:
_log(
config,
f"muse-code adapter: {method} {pathname} {status} | {', '.join(notes)}",
Expand Down Expand Up @@ -730,6 +789,9 @@ def _send_upstream_headers(self, status: int, headers: Any) -> None:
self._headers_sent = True

def _write_upstream_headers(self, headers: Any) -> None:
# Identify the adapter on every relayed answer, so a captured response
# says whether the loopback hop happened and which version shaped it.
self.send_header("x-muse-adapter", str(ADAPTER_VERSION))
for name, value in headers.items():
if name.lower() in _RESPONSE_SKIP:
continue
Expand Down Expand Up @@ -831,6 +893,7 @@ def start_adapter(
upstream: str | None = None,
ports: Iterable[int] | None = None,
log: Callable[[str], None] | None = None,
error_log: Callable[[str], None] | None = None,
passthrough: bool | None = None,
) -> RunningAdapter:
"""Start the loopback adapter, or return the one already running.
Expand All @@ -841,6 +904,11 @@ def start_adapter(
registrations never start a duplicate server; a call with different options
stops the previous adapter and replaces it.

``log`` receives the per-request diagnostic line; ``error_log`` receives the
same shape for refused requests and defaults to ``log``. Neither callback is
part of the identity key: an already-running adapter keeps the callbacks it
was started with.

``passthrough`` defaults to ``MUSE_CODE_ADAPTER=off``: the proxy stays in
place, the wire rules are skipped.
"""
Expand All @@ -861,6 +929,7 @@ def start_adapter(
upstream=resolved_upstream,
passthrough=resolved_passthrough,
log=log,
error_log=error_log if error_log is not None else log,
)
server: _AdapterServer | None = None
last_error: OSError | None = None
Expand Down Expand Up @@ -903,3 +972,46 @@ def stop_adapter() -> None:
active = state.active
if active is not None:
active.close()


def _main(argv: list[str]) -> int:
"""Ask a listening adapter which build it is: ``--health <base_url|origin>``."""
import argparse

parser = argparse.ArgumentParser(
prog="muse_adapter",
description="Diagnostics for the local Muse Code wire adapter.",
)
parser.add_argument(
"--health",
metavar="URL",
help=f"query an adapter, e.g. http://127.0.0.1:43219/v1 (GET {HEALTH_PATH})",
)
args = parser.parse_args(argv)
if not args.health:
parser.print_help()
return 2

origin = args.health.strip().rstrip("/")
if origin.endswith("/v1"):
origin = origin[: -len("/v1")]
url = origin + HEALTH_PATH
try:
with urllib.request.urlopen(url, timeout=5) as response:
payload = json.loads(response.read().decode("utf-8"))
header = response.headers.get("x-muse-adapter")
except Exception as error: # noqa: BLE001 - this command reports, it does not raise
print(
f"no Muse Code adapter answered at {url} ({type(error).__name__}: {error})",
file=sys.stderr,
)
return 1

if header is not None and str(payload.get("adapter_version")) != str(header):
payload["header_version"] = header
print(json.dumps(payload, indent=2, sort_keys=True))
return 0


if __name__ == "__main__":
raise SystemExit(_main(sys.argv[1:]))
Loading
Loading