Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

fix(mcp): identify remote HTTP requests and allow User-Agent overrides

xp98db8a46d9bb
diff --git a/docs/cli-mcp.md b/docs/cli-mcp.md
index 71319df3..b9d8183e 100644
--- a/docs/cli-mcp.md
+++ b/docs/cli-mcp.md
@@ -304,6 +304,7 @@ the server is ready.
| `LAYA_DEFAULT_MODEL` | `multilingual` | The checkpoint a state with no language evidence falls back to, same meaning as in `laya.serve`. Unlike `laya.serve`, an unresolvable name does not stop the server: it comes back as a `router construction failed` tool error on the next call, because a stdio server has no startup to refuse. |
| `LAYA_BASE_URL` | unset | Send predictions to a `laya-serve` on your own hardware instead of loading checkpoints in each MCP process. A bare `host:port` is read as HTTP. |
| `LAYA_REMOTE_TIMEOUT` | `300` | HTTP timeout in seconds when `LAYA_BASE_URL` is set, including the server's cold load. Invalid or non-positive values use the default. |
+| `LAYA_USER_AGENT` | `laya/<version>` | User-Agent for remote HTTP requests. Read when the remote Router is constructed; empty or space/tab-only values use the default. Invalid header values raise a configuration error. Ignored in local mode. |
| `LAYA_API_KEY` | unset | Bearer token sent with every remote request when `LAYA_BASE_URL` is set. Required by a `laya-serve` that set its own `LAYA_API_KEY`; ignored in local mode. |
### Share one model server across MCP sessions
@@ -339,6 +340,19 @@ Set the same `LAYA_API_KEY` in both processes when the server requires a bearer
`LAYA_DEFAULT_MODEL` and `LAYA_AUTO_TASK` aligned so local routing previews match the server's
actual routing. Device and preload settings belong to the HTTP server. The first call after an
idle unload waits for a cold load; raise `LAYA_REMOTE_TIMEOUT` if that takes longer than 300 seconds.
+
+Remote requests identify the library as `laya/<laya.__version__>`. An operator can use that
+prefix in an allowlist, or set `LAYA_USER_AGENT` for a deployment-specific identity. This header
+does not replace bearer authentication or guarantee acceptance by a proxy's security policy.
+When embedding `RemoteRouter` directly, its keyword-only `user_agent` argument takes precedence
+over the environment. `None` reads the environment; an explicit empty or space/tab-only string
+selects the default. The selected value is checked before surrounding spaces/tabs are trimmed:
+CR/LF, other ASCII controls except tab, DEL, and non-Latin-1 characters raise an error naming
+`LAYA_USER_AGENT`. Unlike an invalid timeout, an invalid header is never silently replaced.
+Each Router keeps the value resolved at construction; environment changes require a new Router
+or a restarted MCP process. An explicit request header also takes precedence over a UA set on
+a custom urllib opener; use this setting instead of that workaround.
+
`laya_shortlist`, `laya_tournament`, and prediction hook overrides return `unsupported_remote`, since these
paths run in the model process. For shared-server tournament selection, enable
[`LAYA_TOURNAMENT_GROUP` on the HTTP server](http-api.md#large-choices-laya_tournament_group) and call
diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py
index 9951739b..526a6032 100644
--- a/laya/mcp/remote.py
+++ b/laya/mcp/remote.py
@@ -29,6 +29,7 @@ import urllib.request
import urllib.parse
from typing import Any, Dict, List, Optional, Sequence, Union
+from .. import __version__
from ..router import Router
from ..serve import BODY_CONTROLS, BODY_REFUSALS
@@ -59,16 +60,31 @@ def _timeout_from_env() -> float:
return seconds if math.isfinite(seconds) and seconds > 0 else DEFAULT_TIMEOUT_S
+def _resolve_user_agent(value: Optional[str]) -> str:
+ raw = os.environ.get("LAYA_USER_AGENT", "") if value is None else value
+ if not isinstance(raw, str):
+ raise TypeError("user_agent must be a string or None")
+ # Unlike a bad timeout, an invalid header must fail rather than hide control characters
+ # behind a default. Check before trimming so trailing CR/LF cannot disappear.
+ if any((ord(char) < 32 and char != "\t") or ord(char) == 127 or ord(char) > 255 for char in raw):
+ raise ValueError("LAYA_USER_AGENT / user_agent must be a single Latin-1 header value without control characters")
+ return raw.strip(" \t") or "laya/" + __version__
+
+
class RemoteRouter(Router):
"""Route locally, answer from a ``laya-serve`` at ``base_url``.
``base_url`` is the server origin (``http://127.0.0.1:8000``); the ``/v1/systemone`` paths are
appended here. ``api_key``, when given, is sent as ``Authorization: Bearer`` and must match the
server's ``LAYA_API_KEY``.
+
+ ``user_agent`` overrides ``LAYA_USER_AGENT``; ``None`` reads the environment. A selected
+ empty or space/tab-only value uses ``laya/<version>``. Header values must be Latin-1 and
+ contain no ASCII controls other than tab. The value is resolved once at construction.
"""
def __init__(self, base_url: str, api_key: Optional[str] = None,
- timeout: Optional[float] = None, **router_kwargs: Any):
+ timeout: Optional[float] = None, *, user_agent: Optional[str] = None, **router_kwargs: Any):
# device/preload make no sense for a router that never builds an Agent.
router_kwargs.pop("device", None)
router_kwargs.pop("preload", None)
@@ -81,11 +97,12 @@ class RemoteRouter(Router):
self.timeout = _timeout_from_env() if timeout is None else float(timeout)
if not math.isfinite(self.timeout) or self.timeout <= 0:
raise ValueError("timeout must be a finite positive number")
+ self.user_agent = _resolve_user_agent(user_agent)
# ------------------------------------------------------------------ transport
def _request(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
data = None if body is None else json.dumps(body).encode("utf-8")
- headers = {"Accept": "application/json"}
+ headers = {"Accept": "application/json", "User-Agent": self.user_agent}
if data is not None:
headers["Content-Type"] = "application/json"
if self.api_key:
diff --git a/laya/mcp/server.py b/laya/mcp/server.py
index 9adb721d..1c0d01ba 100644
--- a/laya/mcp/server.py
+++ b/laya/mcp/server.py
@@ -32,6 +32,7 @@ Environment (same meaning as laya.serve where it exists):
it to Router, an unresolvable one is a tool error.
LAYA_BASE_URL answer from a running laya-serve over HTTP; unset keeps models local
LAYA_REMOTE_TIMEOUT HTTP timeout in seconds for remote mode (default 300)
+ LAYA_USER_AGENT remote HTTP client identity (default laya/<version>)
"""
from __future__ import annotations
diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py
index 6b9aebac..05e81bba 100644
--- a/tests/test_hooks_api.py
+++ b/tests/test_hooks_api.py
@@ -206,9 +206,11 @@ for _name, _scores, _labels, _kwargs, _error in (
from laya.mcp.remote import RemoteRouter # noqa: E402
check_true("RemoteRouter/is a Router", issubclass(RemoteRouter, Router))
-check_param("RemoteRouter.__init__", RemoteRouter.__init__, "base_url", inspect.Parameter.empty)
-check_param("RemoteRouter.__init__", RemoteRouter.__init__, "api_key", None)
-check_param("RemoteRouter.__init__", RemoteRouter.__init__, "timeout", None)
+check_param("RemoteRouter.__init__", RemoteRouter.__init__, "base_url", inspect.Parameter.empty,
+ inspect.Parameter.POSITIONAL_OR_KEYWORD)
+check_param("RemoteRouter.__init__", RemoteRouter.__init__, "api_key", None, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+check_param("RemoteRouter.__init__", RemoteRouter.__init__, "timeout", None, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+check_param("RemoteRouter.__init__", RemoteRouter.__init__, "user_agent", None, inspect.Parameter.KEYWORD_ONLY)
for method in ("predict", "predict_batch"):
check("RemoteRouter/%s signature" % method,
[(p.name, p.kind, p.default) for p in sig(getattr(RemoteRouter, method)).values()],
diff --git a/tests/test_mcp_remote.py b/tests/test_mcp_remote.py
index 21d86a5e..a9c06e19 100644
--- a/tests/test_mcp_remote.py
+++ b/tests/test_mcp_remote.py
@@ -12,6 +12,7 @@ import pytest
pytest.importorskip("mcp")
+from laya import __version__ # noqa: E402
from laya.mcp import server as mcp_server # noqa: E402
from laya.mcp.tools import ( # noqa: E402
ToolError, laya_decide, laya_predict, laya_predict_batch, laya_preset, laya_route, laya_route_batch,
@@ -34,6 +35,7 @@ class FakeServe(BaseHTTPRequestHandler):
"""Records every request; answers /health and /v1/systemone like laya-serve."""
requests: list = []
+ user_agents: list = []
status_override: int | None = None
detail_override: str = "bad request"
require_bearer: str | None = None
@@ -51,6 +53,7 @@ class FakeServe(BaseHTTPRequestHandler):
def do_GET(self):
FakeServe.requests.append(("GET", self.path, None, dict(self.headers)))
+ FakeServe.user_agents.append(self.headers.get_all("User-Agent"))
if self.path == "/health":
if FakeServe.require_bearer and self.headers.get("Authorization") != "Bearer " + FakeServe.require_bearer:
return self._send(200, {"status": "ok"})
@@ -61,6 +64,7 @@ class FakeServe(BaseHTTPRequestHandler):
length = int(self.headers.get("Content-Length") or 0)
body = json.loads(self.rfile.read(length)) if length else None
FakeServe.requests.append(("POST", self.path, body, dict(self.headers)))
+ FakeServe.user_agents.append(self.headers.get_all("User-Agent"))
if FakeServe.require_bearer and self.headers.get("Authorization") != "Bearer " + FakeServe.require_bearer:
return self._send(401, {"detail": "invalid or missing bearer token"})
if FakeServe.status_override:
@@ -70,9 +74,15 @@ class FakeServe(BaseHTTPRequestHandler):
self._send(404, {"detail": "Not Found"})
[email protected](autouse=True)
+def isolated_user_agent(monkeypatch):
+ monkeypatch.delenv("LAYA_USER_AGENT", raising=False)
+
+
@pytest.fixture
def serve():
FakeServe.requests = []
+ FakeServe.user_agents = []
FakeServe.status_override = None
FakeServe.require_bearer = None
httpd = HTTPServer(("127.0.0.1", 0), FakeServe)
@@ -118,8 +128,83 @@ def test_bearer_token_is_sent_when_configured(serve):
assert info.value.code == "unauthorized"
[email protected]("source", ["default", "environment", "argument"])
+def test_user_agent_identifies_every_remote_request(monkeypatch, serve, source):
+ expected = "laya/" + __version__
+ kwargs = {}
+ if source != "default":
+ monkeypatch.setenv("LAYA_USER_AGENT", "deployment/1.0")
+ expected = "deployment/1.0"
+ if source == "argument":
+ kwargs["user_agent"] = "embedded/2.0"
+ expected = "embedded/2.0"
+ FakeServe.require_bearer = "test-key"
+ router = RemoteRouter(serve, "test-key", 2, **kwargs)
+ assert router.health() == HEALTH
+ assert router.predict("single", _questions()) == ANSWER
+ items = [{"state": state, "questions": _questions()} for state in ("first", "second")]
+ assert router.predict_batch(items) == [ANSWER, ANSWER]
+ assert FakeServe.user_agents == [[expected]] * 4
+ assert [r[:2] for r in FakeServe.requests] == [("GET", "/health")] + [("POST", "/v1/systemone")] * 3
+ assert [r[2] for r in FakeServe.requests[1:]] == [
+ {"state": state, "questions": _questions()} for state in ("single", "first", "second")
+ ]
+ assert all(r[3]["Authorization"] == "Bearer test-key" for r in FakeServe.requests)
+ assert all(r[3]["Accept"] == "application/json" for r in FakeServe.requests)
+ assert "Content-Type" not in FakeServe.requests[0][3]
+ assert all(r[3]["Content-Type"] == "application/json" for r in FakeServe.requests[1:])
+
+
[email protected]("raw, expected", [
+ ("", None), (" \t ", None), (" \tcustom/1.0 (caf\xe9)\t details \t", "custom/1.0 (caf\xe9)\t details"),
+])
[email protected]("source", ["environment", "argument"])
+def test_user_agent_trims_only_outer_spaces_and_tabs(monkeypatch, serve, raw, expected, source):
+ monkeypatch.setenv("LAYA_USER_AGENT", raw if source == "environment" else "environment/1.0")
+ kwargs = {"user_agent": raw} if source == "argument" else {}
+ RemoteRouter(serve, **kwargs).health()
+ assert FakeServe.user_agents == [[expected or "laya/" + __version__]]
+
+
[email protected]("raw", ["x\r", "x\n", "x\r\n folded", "\nx", "x\x01", "x\x7f", "x\u0100"])
[email protected]("source", ["environment", "argument"])
+def test_user_agent_rejects_invalid_header_values_before_http(monkeypatch, serve, raw, source):
+ if source == "environment":
+ monkeypatch.setenv("LAYA_USER_AGENT", raw)
+ kwargs = {"user_agent": raw} if source == "argument" else {}
+ with pytest.raises(ValueError, match="LAYA_USER_AGENT"):
+ RemoteRouter(serve, **kwargs)
+ assert not FakeServe.requests
+
+
+def test_user_agent_rejects_nul_and_non_string_arguments(serve):
+ # NUL cannot be put in an OS environment variable, but can reach the constructor.
+ with pytest.raises(ValueError, match="LAYA_USER_AGENT"):
+ RemoteRouter(serve, user_agent="x\x00")
+ for value in (False, 42, b"client/1.0"):
+ with pytest.raises(TypeError, match="user_agent"):
+ RemoteRouter(serve, user_agent=value)
+ assert not FakeServe.requests
+
+
+def test_user_agent_argument_does_not_read_an_invalid_environment(monkeypatch, serve):
+ monkeypatch.setenv("LAYA_USER_AGENT", "bad\nvalue")
+ RemoteRouter(serve, user_agent="embedded/1.0").health()
+ assert FakeServe.user_agents == [["embedded/1.0"]]
+
+
+def test_user_agent_is_resolved_once_per_router(monkeypatch, serve):
+ monkeypatch.setenv("LAYA_USER_AGENT", "first/1.0")
+ first = RemoteRouter(serve)
+ monkeypatch.setenv("LAYA_USER_AGENT", "second/1.0")
+ second = RemoteRouter(serve)
+ first.health()
+ second.health()
+ assert FakeServe.user_agents == [["first/1.0"], ["second/1.0"]]
+
+
@pytest.mark.parametrize("status, code", [(400, "invalid_request"), (422, "invalid_request"),
- (503, "busy"), (500, "upstream_error")])
+ (403, "upstream_error"), (503, "busy"), (500, "upstream_error")])
def test_http_errors_map_to_tool_error_codes(serve, status, code):
FakeServe.status_override = status
FakeServe.detail_override = "question 'dept': criteria must be an object"
@@ -233,13 +318,33 @@ def test_tournament_is_refused_before_remote_requests(serve, n):
def test_server_builds_a_remote_router_from_the_environment(monkeypatch, serve):
monkeypatch.setenv("LAYA_BASE_URL", serve + "/")
monkeypatch.setenv("LAYA_API_KEY", "k")
+ monkeypatch.setenv("LAYA_USER_AGENT", "mcp-deployment/1.0")
monkeypatch.setattr(mcp_server, "_ROUTER", None)
router = mcp_server._ensure_router()
assert isinstance(router, RemoteRouter)
assert router.base_url == serve and router.api_key == "k"
+ assert router.health() == HEALTH
+ assert FakeServe.user_agents == [["mcp-deployment/1.0"]]
monkeypatch.setattr(mcp_server, "_ROUTER", None)
+def test_user_agent_configuration_error_is_remote_only(monkeypatch, serve):
+ monkeypatch.setenv("LAYA_BASE_URL", serve)
+ monkeypatch.setenv("LAYA_USER_AGENT", "bad\nvalue")
+ monkeypatch.setattr(mcp_server, "_ROUTER", None)
+ with pytest.raises(ToolError, match="LAYA_USER_AGENT") as info:
+ mcp_server._ensure_router()
+ assert info.value.code == "internal_error"
+ assert mcp_server._ROUTER is None
+ assert not FakeServe.requests
+ monkeypatch.delenv("LAYA_BASE_URL")
+ monkeypatch.delenv("LAYA_THREADS", raising=False)
+ monkeypatch.setenv("LAYA_PRELOAD", "0")
+ router = mcp_server._ensure_router()
+ assert not isinstance(router, RemoteRouter)
+ assert not router._agents
+
+
@pytest.mark.parametrize("raw, expected", [("", None), (" ", None), ("127.0.0.1:8123", "http://127.0.0.1:8123"),
("http://h:1/", "http://h:1"), ("https://laya.example", "https://laya.example")])
def test_base_url_normalisation(monkeypatch, raw, expected):
diff --git a/tests/test_packaging.py b/tests/test_packaging.py
index 9af2b2f4..9cd9b62b 100644
--- a/tests/test_packaging.py
+++ b/tests/test_packaging.py
@@ -946,8 +946,8 @@ def env_reads(excluded_paths=()):
read_names = env_reads(("laya/mcp/server.py", "laya/mcp/remote.py"))
-check("nix/only the two MCP transport variables are excluded from the HTTP process",
- sorted(env_reads() - read_names), ["LAYA_BASE_URL", "LAYA_REMOTE_TIMEOUT"])
+check("nix/only the MCP transport variables are excluded from the HTTP process",
+ sorted(env_reads() - read_names), ["LAYA_BASE_URL", "LAYA_REMOTE_TIMEOUT", "LAYA_USER_AGENT"])
# An assignment only. The `models` description names `LAYA_MODELS` in prose, and prose that
# mentions a variable sets nothing.
assigned = sorted(set(re.findall(r'\b(LAYA_[A-Z0-9_]+)\s*=', nix_module))